{"id":13861737,"url":"https://github.com/markusstraub/mdsplit","last_synced_at":"2026-01-07T15:59:00.994Z","repository":{"id":41339696,"uuid":"500437311","full_name":"markusstraub/mdsplit","owner":"markusstraub","description":"mdsplit is a python command line tool to split Markdown files into chapters at a given heading level","archived":false,"fork":false,"pushed_at":"2024-10-19T21:14:37.000Z","size":76,"stargazers_count":43,"open_issues_count":3,"forks_count":8,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-11-19T22:53:22.303Z","etag":null,"topics":["markdown","splitter"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markusstraub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-06T13:07:34.000Z","updated_at":"2024-11-07T14:24:55.000Z","dependencies_parsed_at":"2024-08-05T06:13:54.612Z","dependency_job_id":null,"html_url":"https://github.com/markusstraub/mdsplit","commit_stats":{"total_commits":34,"total_committers":2,"mean_commits":17.0,"dds":0.02941176470588236,"last_synced_commit":"53cbfa8b35e4f15ac585ae1f630949bcba983664"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusstraub%2Fmdsplit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusstraub%2Fmdsplit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusstraub%2Fmdsplit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markusstraub%2Fmdsplit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markusstraub","download_url":"https://codeload.github.com/markusstraub/mdsplit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225968872,"owners_count":17553149,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["markdown","splitter"],"created_at":"2024-08-05T06:01:29.118Z","updated_at":"2026-01-07T15:59:00.976Z","avatar_url":"https://github.com/markusstraub.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# mdsplit\n\n`mdsplit` is a python command line tool to\n**split Markdown files** into chapters\n**at a given [heading level](https://spec.commonmark.org/0.31.2/#atx-headings)**.\n\nEach chapter (or subchapter) is written to its own file,\nwhich is named after the heading title.\nThese files are written to subdirectories representing the document's structure.\n\nOptionally you can create:\n- table of contents (`toc.md`) for each input file\n- navigation footers (links to table of contents, previous page, next page)\n\n**Note:**\n- *Code blocks* (`` ``` ``) are detected (and headers inside ignored)\n- The output is *guaranteed to be identical* with the input\n  (except for the separation into multiple files of course)\n    - This means: no touching of whitespace or changing `-` to `*` of your lists\n      like some viusual Markdown editors tend to do\n- Text before the first heading is written to a file with the same name as the Markdown file\n- Chapters with the same heading name are written to the same file.\n- Reading from `stdin` is supported\n- Can easily handle large files,\n  e.g. a 1 GB file is split into 30k files in 35 seconds on a 2015 Thinkpad (with an SSD)\n\n**Limitations:**\n- Only [ATX headings](https://spec.commonmark.org/0.31.2/#atx-headings)\n  such as `# Heading 1` are supported.\n  [Setext headings](https://spec.commonmark.org/0.31.2/#setext-headings)\n  (underlined headings) are not recognised.\n\n```\npositional arguments:\n  input                 path to input file/folder (omit or set to '-' to read from stdin)\n\noptions:\n  -h, --help            show this help message and exit\n  -e ENCODING, --encoding ENCODING\n                        force a specific encoding, default: python's default platform encoding\n  -l {1,2,3,4,5,6}, --max-level {1,2,3,4,5,6}\n                        maximum heading level to split, default: 1\n  -t, --table-of-contents\n                        generate a table of contents (one 'toc.md' per input file)\n  -n, --navigation      add a navigation footer on each page (links to toc, previous page, next page)\n  -o OUTPUT, --output OUTPUT\n                        path to output folder (must not exist)\n  -f, --force           write into output folder even if it already exists\n  -v, --verbose\n```\n\n**Similar projects:**\n\nYou may also be interested in https://github.com/alandefreitas/mdsplit (C++-based).\n\n## Installation\n\nEither use pip:\n\n    pip install mdsplit\n    mdsplit\n\nOr simply download [mdsplit.py](mdsplit.py) and run it (it does not use any dependencies but python itself):\n\n    python3 mdsplit.py\n\n## Usage\n\n**Show documentation and supported arguments**:\n\n```bash\nmdsplit --help\n```\n\n**Split a file at level 1 headings**, e.g. `# This Heading`, and write results to an output folder based on the input name:\n\n```bash\nmdsplit in.md\n```\n\n```mermaid\n%%{init: {'themeVariables': { 'fontFamily': 'Monospace', 'text-align': 'left'}}}%%\nflowchart LR\n    subgraph in.md\n        SRC[# Heading 1\u003cbr\u003elorem ipsum\u003cbr\u003e\u003cbr\u003e# HeadingTwo\u003cbr\u003edolor sit amet\u003cbr\u003e\u003cbr\u003e## Heading 2.1\u003cbr\u003econsetetur sadipscing elitr]\n    end\n    SRC --\u003e MDSPLIT(mdsplit in.md)\n    MDSPLIT --\u003e SPLIT_A\n    MDSPLIT --\u003e SPLIT_B\n    subgraph in/HeadingTwo.md\n        SPLIT_B[# HeadingTwo\u003cbr\u003edolor sit amet\u003cbr\u003e\u003cbr\u003e## Heading 2.1\u003cbr\u003econsetetur sadipscing elitr]\n    end\n    subgraph in/Heading 1.md\n        SPLIT_A[# Heading 1\u003cbr\u003elorem ipsum\u003cbr\u003e\u003cbr\u003e]\n    end\n    style SRC text-align:left\n    style SPLIT_A text-align:left\n    style SPLIT_B text-align:left\n    style MDSPLIT fill:#000,color:#0F0\n```\n\n**Split a file at level 2 headings** and higher, e.g. `# This Heading` and `## That Heading`, and write to a specific output directory:\n\n```bash\nmdsplit in.md --max-level 2 --output out\n```\n\n```mermaid\n%%{init: {'themeVariables': { 'fontFamily': 'Monospace', 'text-align': 'left'}}}%%\nflowchart LR\n    subgraph in.md\n        SRC[# Heading 1\u003cbr\u003elorem ipsum\u003cbr\u003e\u003cbr\u003e# HeadingTwo\u003cbr\u003edolor sit amet\u003cbr\u003e\u003cbr\u003e## Heading 2.1\u003cbr\u003econsetetur sadipscing elitr]\n    end\n    SRC --\u003e MDSPLIT(mdsplit in.md -l 2 -o out)\n    subgraph out/HeadingTwo/Heading 2.1.md\n        SPLIT_C[## Heading 2.1\u003cbr\u003econsetetur sadipscing elitr]\n    end\n    subgraph out/HeadingTwo.md\n        SPLIT_B[# HeadingTwo\u003cbr\u003edolor sit amet\u003cbr\u003e\u003cbr\u003e]\n    end\n    subgraph out/Heading 1.md\n        SPLIT_A[# Heading 1\u003cbr\u003elorem ipsum\u003cbr\u003e\u003cbr\u003e]\n    end\n    MDSPLIT --\u003e SPLIT_A\n    MDSPLIT --\u003e SPLIT_B\n    MDSPLIT --\u003e SPLIT_C\n    style SRC text-align:left\n    style SPLIT_A text-align:left\n    style SPLIT_B text-align:left\n    style MDSPLIT fill:#000,color:#0F0\n```\n\n**Split Markdown from stdin**:\n\n```bash\ncat in.md | mdsplit --output out\n```\n\n## Development (Ubuntu 24.04)\n\nAdd the [deadsnakes PPA](https://launchpad.net/~deadsnakes/+archive/ubuntu/ppa)\nand install additional python versions for testing\n\n```bash\nsudo add-apt-repository ppa:deadsnakes/ppa\nsudo apt install python3.9-distutils python3.9-venv\n...\n```\n\nInstall [poetry](https://python-poetry.org)\n\nPrepare virtual environment and download dependencies\n\n    poetry install\n\nRun tests (for the default python version)\n\n    poetry run pytest\n\nRun tests for all supported python versions\n\n    poetry run tox\n\nRelease new version\n\n    poetry build\n    poetry publish\n\n[Download statistics](https://pypistats.org/packages/mdsplit)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkusstraub%2Fmdsplit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkusstraub%2Fmdsplit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkusstraub%2Fmdsplit/lists"}