ndx 0.5.0

Installation

pipx install ndx

Usage

To generate an index in a specific directory, use:

ndx /path/to/directory

Generate index files recursively:

ndx --recursive /path/to/directory

usage: ndx [-h] [-r] [--max-depth MAX_DEPTH] [-f] [-v] [--version] directory

Build an annotated index file for a directory.

positional arguments:
directory             path to the target directory

options:
-h, --help            show this help message and exit
-r, --recursive       build index files recursively (default: False)
--max-depth MAX_DEPTH
                        maximum recursion depth for building index files (default: 50)
-f, --force           overwrite existing index.html file(s) (default: False)
-v, --verbose         enable verbose logging (default: False)
--version             show program's version number and exit

Configuration

To customize the index by adding descriptions to the page and files, place a .ndx.json file in the target directory.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "page": {
            "type": "object",
            "properties": {"description": {"type": "string", "maxLength": 10000}},
            "required": ["description"],
            "additionalProperties": false,
        },
        "files": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name_regex": {
                        "type": "string",
                        "maxLength": 200,
                        "format": "re2-pattern",
                    },
                    "description": {"type": "string", "maxLength": 1000},
                },
                "required": ["name_regex", "description"],
                "additionalProperties": false,
            },
        },
    },
    "additionalProperties": false,
}

{
  "page": {
    "description": "For more information, please refer to the <a href='https://docs.example.com'>documentation</a> website."
  },
  "files": [
    {
      "name_regex": ".*\\.pdf$",
      "description": "Full documentation"
    },
    {
      "name_regex": ".*\\.log$",
      "description": "Build logs"
    }
  ]
}

Design Choices and Limitations

• Data integrity is only guaranteed on POSIX-compliant systems.

• Only RE2 regexes are supported.

• Descriptions only support HTML anchor tags (<a href=''>...</a>).

• Only HTTPS links are supported in the descriptions.

• All attributes except the link target are stripped from the HTML anchor tags and target="_blank" is added to them.

• Hidden files (starting with .) and the index file index.html are skipped.

• A warning is issued and notes are skipped for files that match multiple regexes.

• Support for hardlinks on the target directory is required unless the --force option is used.

History

This script was originally developed for the linkmedic project.

License

• Copyright 2025-2026 M. Farzalipour Tabriz, Max Planck Institute for Physics (MPP)

All rights reserved.

This software may be modified and distributed under the terms of the GPL-3.0 (or later) License. See the LICENSE file for details.