{"id":16890886,"url":"https://github.com/alandefreitas/mdsplit","last_synced_at":"2025-04-11T13:10:23.168Z","repository":{"id":139489988,"uuid":"300107878","full_name":"alandefreitas/mdsplit","owner":"alandefreitas","description":"Generate documentation from bulky README.md files","archived":false,"fork":false,"pushed_at":"2021-01-11T20:27:44.000Z","size":1201,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-25T09:21:41.013Z","etag":null,"topics":["documentation","documentation-generator","github-pages","markdown"],"latest_commit_sha":null,"homepage":"https://alandefreitas.github.io/mdsplit/","language":"C++","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/alandefreitas.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":"2020-10-01T01:38:12.000Z","updated_at":"2024-04-29T12:43:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"7fcc34c8-d83d-4280-ad8a-96f13739624a","html_url":"https://github.com/alandefreitas/mdsplit","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alandefreitas%2Fmdsplit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alandefreitas%2Fmdsplit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alandefreitas%2Fmdsplit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alandefreitas%2Fmdsplit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alandefreitas","download_url":"https://codeload.github.com/alandefreitas/mdsplit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248405014,"owners_count":21097874,"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":["documentation","documentation-generator","github-pages","markdown"],"created_at":"2024-10-13T17:04:50.307Z","updated_at":"2025-04-11T13:10:23.158Z","avatar_url":"https://github.com/alandefreitas.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mdsplit\n\n\u003e Generate your documentation from bulky README.md files\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://alandefreitas.github.io/mdsplit/\"\u003e\n        \u003cimg src=\"https://img.icons8.com/nolan/2x/split-files.png\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\nGithub is full of mid-sized projects that help us solve specific tasks. Authors tend to document these repositories with\nbeautiful README.md files and some auxiliary documents.\n\n`mdsplit` is a tool that splits these bulky README.md files into smaller files in a way compatible with GitHub Pages +\nGitHub Actions + MkDocs. GitHub Actions will then regenerate the documentation whenever your `README.md` file is\nupdated.\n\n\u003c!-- START mdsplit-ignore --\u003e\n\u003cbr/\u003e\n\nSee the mdsplit [LIVE DEMO](https://alandefreitas.github.io/mdsplit/) and compare it with this\nvery [`README.md`](README.md) file.\n\u003c!-- END mdsplit-ignore --\u003e\n\n\u003cbr/\u003e\n\n[![Build Status](https://img.shields.io/github/workflow/status/alandefreitas/mdsplit/Build%20mdsplit?event=push\u0026label=Build\u0026logo=Github-Actions)](https://github.com/alandefreitas/mdsplit/actions?query=workflow%3A%22Build+mdsplit%22+event%3Apush)\n[![Latest Release](https://img.shields.io/github/release/alandefreitas/mdsplit.svg?label=Download)](https://GitHub.com/alandefreitas/mdsplit/releases/)\n[![Documentation](https://img.shields.io/website-up-down-green-red/http/alandefreitas.github.io/mdsplit.svg?label=Documentation)](https://alandefreitas.github.io/mdsplit/)\n[![Discussions](https://img.shields.io/website-up-down-green-red/http/alandefreitas.github.io/mdsplit.svg?label=Discussions)](https://github.com/alandefreitas/mdsplit/discussions)\n\n\u003cbr/\u003e\n\n[![Facebook](https://img.shields.io/twitter/url/http/shields.io.svg?style=social\u0026label=Share+on+Facebook\u0026logo=facebook)](https://www.facebook.com/sharer/sharer.php?t=mdsplit:%20split%20a%20bulky%20README.md%20into%20a%20nice%20documentation\u0026u=https://github.com/alandefreitas/mdsplit/)\n[![QZone](https://img.shields.io/twitter/url/http/shields.io.svg?style=social\u0026label=Share+on+QZone\u0026logo=qzone)](http://sns.qzone.qq.com/cgi-bin/qzshare/cgi_qzshare_onekey?url=https://github.com/alandefreitas/mdsplit/\u0026title=mdsplit:%20split%20a%20bulky%20README.md%20into%20a%20nice%20documentation\u0026summary=mdsplit:%20split%20a%20bulky%20README.md%20into%20a%20nice%20documentation)\n[![Weibo](https://img.shields.io/twitter/url/http/shields.io.svg?style=social\u0026label=Share+on+Weibo\u0026logo=sina-weibo)](http://sns.qzone.qq.com/cgi-bin/qzshare/cgi_qzshare_onekey?url=https://github.com/alandefreitas/mdsplit/\u0026title=mdsplit:%20split%20a%20bulky%20README.md%20into%20a%20nice%20documentation\u0026summary=mdsplit:%20split%20a%20bulky%20README.md%20into%20a%20nice%20documentation)\n[![Reddit](https://img.shields.io/twitter/url/http/shields.io.svg?style=social\u0026label=Share+on+Reddit\u0026logo=reddit)](http://www.reddit.com/submit?url=https://github.com/alandefreitas/mdsplit/\u0026title=mdsplit:%20split%20a%20bulky%20README.md%20into%20a%20nice%20documentation)\n[![Twitter](https://img.shields.io/twitter/url/http/shields.io.svg?label=Share+on+Twitter\u0026style=social)](https://twitter.com/intent/tweet?text=mdsplit:%20split%20a%20bulky%20README.md%20into%20a%20nice%20documentation\u0026url=https://github.com/alandefreitas/mdsplit/\u0026hashtags=Markdown,Documentation,DocumentationGenerator,GithubPages)\n[![LinkedIn](https://img.shields.io/twitter/url/http/shields.io.svg?style=social\u0026label=Share+on+LinkedIn\u0026logo=linkedin)](https://www.linkedin.com/shareArticle?mini=false\u0026url=https://github.com/alandefreitas/mdsplit/\u0026title=mdsplit:%20split%20a%20bulky%20README.md%20into%20a%20nice%20documentation)\n[![WhatsApp](https://img.shields.io/twitter/url/http/shields.io.svg?style=social\u0026label=Share+on+WhatsApp\u0026logo=whatsapp)](https://api.whatsapp.com/send?text=mdsplit:%20split%20a%20bulky%20README.md%20into%20a%20nice%20documentation:+https://github.com/alandefreitas/mdsplit/)\n[![Line.me](https://img.shields.io/twitter/url/http/shields.io.svg?style=social\u0026label=Share+on+Line.me\u0026logo=line)](https://lineit.line.me/share/ui?url=https://github.com/alandefreitas/mdsplit/\u0026text=mdsplit:%20split%20a%20bulky%20README.md%20into%20a%20nice%20documentation)\n[![Telegram.me](https://img.shields.io/twitter/url/http/shields.io.svg?style=social\u0026label=Share+on+Telegram.me\u0026logo=telegram)](https://telegram.me/share/url?url=https://github.com/alandefreitas/mdsplit/\u0026text=mdsplit:%20split%20a%20bulky%20README.md%20into%20a%20nice%20documentation)\n[![HackerNews](https://img.shields.io/twitter/url/http/shields.io.svg?style=social\u0026label=Share+on+HackerNews\u0026logo=y-combinator)](https://news.ycombinator.com/submitlink?u=https://github.com/alandefreitas/mdsplit/\u0026t=mdsplit:%20split%20a%20bulky%20README.md%20into%20a%20nice%20documentation)\n\n\u003cbr/\u003e\n\n\u003c!-- https://gist.github.com/jbroadway/2836900 --\u003e\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\u003cdetails\u003e\n\u003csummary\u003eTable of Contents\u003c/summary\u003e\n\n- [Quick Start](#quick-start)\n  - [Step-by-Step](#step-by-step)\n    - [Splitting Locally](#splitting-locally)\n    - [Testing Locally](#testing-locally)\n    - [Github Actions](#github-actions)\n  - [Options](#options)\n    - [Links to Repository](#links-to-repository)\n    - [Hiding sections](#hiding-sections)\n    - [Input file](#input-file)\n    - [Output directory](#output-directory)\n    - [Remove HTML Tags](#remove-html-tags)\n    - [Front matter](#front-matter)\n    - [Removing old sections](#removing-old-sections)\n  - [Installing](#installing)\n    - [Binaries](#binaries)\n    - [Install from Source](#install-from-source)\n  - [Gallery](#gallery)\n  - [Contributing](#contributing)\n    - [Guidelines](#guidelines)\n    - [Contributors](#contributors)\n\n\u003c/details\u003e\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\u003cbr/\u003e\n\n# Quick Start\n\nGo to your repository settings and turn on GitHub Pages on the branch gh-pages.\n\n![Turn on GitHub Pages](docs/images/turonpages.png)\n\nCopy the [`mkdocs.yml`](mkdocs.yml) file to your repository:\n\n??? info \"See contents\"\n\n    === \"mkdocs.yml\"\n    \n        ```yaml hl_lines=\"1 2 3 4 6 30\"\n        --8\u003c-- \"mkdocs.yml\"\n        ```\n\nCopy the [`.github/workflows/docs.yml`](mkdocs.yml) file to your repository:\n\n??? info \"See contents\"\n\n    === \"docs.yml\"\n    \n        ```yaml hl_lines=\"21 22 31-44 48\"\n        --8\u003c-- \".github/workflows/docs.yml\"\n        ```\n\nIn a few seconds, your README.md file will become a beautiful documentation.\n\n## Step-by-Step\n\n### Splitting Locally\n\nAfter [installing](#binaries) `mdsplit`, run\n\n```bash\nmdsplit -r username/repository\n```\n\nfrom your project root directory to generate your documentation.\n\n`mdsplit` will split your `README.md` file into smaller files and save the results to the `docs` directory.\n\n!!! note This is directory from where mkdocs will later build your documentation.\n\n### Testing Locally\n\nYou might want to test your documentation locally before pushing it to your repository.\n\nInstall mkdocs with\n\n```bash\npip install mkdocs-material\n```\n\nAfter generating the docs with mdsplit, run the mkdocs server with\n\n```bash\nmkdocs serve\n```\n\nOr build the static documentation with\n\n```bash\nmkdocs serve\n```\n\nUse this mkdocs configuration file to get started:\n\n=== \"mkdocs.yml\"\n\n```yaml hl_lines=\"1 2 3 4 6 30\"\n--8\u003c-- \"mkdocs.yml\"\n```\n\nReplace the settings with your repository information.\n\n### Github Actions\n\nYou can integrate `mdsplit` with GitHub actions to regenerate the documentation whenever you change your `README.md`\nfile.\n\nUse this workflow to get started:\n\n=== \".github/workflows/docs.yml\"\n\n    ```yaml hl_lines=\"21 22 31-44 48\"\n    --8\u003c-- \".github/workflows/docs.yml\"\n    ```\n\nReplace the settings with your repository information.\n\nMost steps in this workflow are optional:\n\n* The step `technote-space/toc-generator@v2` creates a table of contents for your README.md file\n* The second step downloads and builds the master version of mdsplit. This is the version we use in this repository, but\n  you probably want to use a more stable version in your own repository. To do that, comment this step and use the third\n  and forth steps instead.\n* The third and fourth steps (commented out) download the latest release version of mdsplit. That's probably what you\n  want for your repository. Uncomment these steps to do that.\n* The next steps are pushing the docs to your master branch. Make any adjustments you might need.\n* The last steps are taking the docs from your master branch and publishing them to your gh-pages branch.\n\n## Options\n\nRun `mdsplit` with the `--help` (or `-h`) option to see all the command-line options:\n\n```bash\nmdsplit -h\n```\n\n```console\nGenerate documentation from README.md files\nUsage:\n  mdsplit -i input_directory -o output_directory -r username/repository\n\n File options:\n  -i, --input arg       Input file (default: README.md)\n  -o, --output arg      Output directory (default: docs)\n  -r, --repository arg  Output repository\n\n Behaviour options:\n  -l, --level arg        Max level for which we should split the file\n                         (default: 6)\n  -c, --clear-html arg   List of HTML tags mdsplit should clear (default:\n                         details,summary)\n  -t, --toc              Create a table of contents for the new files\n                         (default: true)\n  -j, --jekyll-escape    Escape consecutive \"{{\"s for Jekyll processing\n                         (default: true)\n      --header-reindent  Reindent headers to match the new files (default:\n                         true)\n  -f, --front-matter     Include a front-matter in the new files (default:\n                         true)\n  -u, --url-update       Update relative URLs to their new relative paths\n                         (default: true)\n      --remove-auto-toc  Remove automatic table of contents (default: true)\n      --trace            Trace commands (default: true)\n\n Help options:\n  -h, --help     Print usage\n  -v, --version  Print version\n```\n\n### Links to Repository\n\nThe `--repository` (or `-r`) option should be used to provide your repository name to `mdsplit`. This option enables `mdsplit` to create links to files inside the repository.\n\nAlthough all internal repository links work in GitHub, not all internal links are adjusted to work with GitHub Pages.\nDocumentation files can only contain links to other markdown files in the documentation directory.\n\nIf your documentation needs to refer to a file in the repository and this file is not under `.docs/`, links need to use\nthe absolute repository link as a parent path.\n\nFor instance, consider a file `source/main.cpp` outside `docs`. Then\n\n```md\n[My Internal Link](source/main.cpp)\n```\n\nshould become\n\n```md\n[My Internal Link](https://github.com/my_username/my_repository/blob/master/source/main.cpp)\n```\n\nso that the link works correctly on GitHub pages.\n\nYou can use the `--repository` (or `-r`) option to provide the repository `mdsplit` should consider to generate these\nlinks:\n\n```bash\nmdsplit -r alandefreitas/matplotplusplus\n```\n\n### Hiding sections\n\nUse the comments `\u003c!-- START mdsplit-ignore --\u003e` and `\u003c!-- END mdsplit-ignore --\u003e` to ignore sections from\nyour `README.md`. For instance:\n\n=== \"Markdown\"\n\n    ```md\n    \u003c!-- START mdsplit-ignore --\u003e\n    # Section to ignore\n    \n    `mdsplit` will remove this whole section from your documentation.\n    \n    \u003c!-- END mdsplit-ignore --\u003e\n    ```\n\nor\n\n=== \"Markdown\"\n\n    ```md\n    # Section to ignore\n    \n    \u003c!-- START mdsplit-ignore --\u003e\n    `mdsplit` will remove this paragraph from your documentation.\n    \u003c!-- END mdsplit-ignore --\u003e\n    ```\n\nIf you ignore the complete section, `mdsplit` will create no file for that section.\n\nIf you're reading this from [`README.md`](README.md) you will see this section has a subsection that will be completely\nignored in the documentation.\n\n\u003c!-- START mdsplit-ignore --\u003e\n\n#### Ignored section\n\nThis section will be completely ignored by the documentation. Have a look at the\nSection [Hiding sections from docs](https://alandefreitas.github.io/mdsplit/options/hiding-sections-from-docs.html) in\nthe documentation.\n\u003c!-- END mdsplit-ignore --\u003e\n\n### Input file\n\nThe `--input` (or `-i`) option defines the file `mdsplit` should split to generate the documentation. You don't usually\nwant to change the default from `README.md` because that's the file GitHub uses for all repositories.\n\nHowever, it might be useful to use another file as input if you want to have your documentation in a bulky markdown file\nkept separate from your main `README.md`.\n\n### Output directory\n\nThe `--output` (or `-o`) option defines the directory where `mdsplit` should store the documentation. You don't usually want to change the default from `docs` because GitHub Pages gives you only two options for the documentation directory:\n\n![](docs/images/pages_dirs.png)\n\nAnd cluttering the root directory with lots of markdown files and directories is not a good idea unless you are going to\ncreate another branch for your documentation.\n\n### Remove HTML Tags\n\nThe `--clear-html` (or `-d`) option defines the HTML tags `mdsplit` should remove from your `README.md`. This is useful\nto `README.md` files that use tags such as `details` and `summary` to emulate what the documentation would look like\ninside the `README.md` file.\n\nBy default, `mdsplit` will remove the tags `details` and `summary` because 1) Jekyll themes often have difficulty with\nthese tags and 2) people often use these tags in markdown files to emulate what the documentation would look like.\n\n### Front matter\n\nThe `--front-matter` (or `-f`) option tells `mdsplit` to generate a front matter for each new file. The default option\nis `true` so you need `--front-matter=false` to turn it off.\n\nThis front matter includes parameters such as `title`, `nav_order`, `parent`, `has_children`, and `nav_exclude` for each\nmarkdown file.\n\nJekyll themes can use these parameters to generate proper navigation bars, order pages, and define page titles.\n\n### Removing old sections\n\nIn principle, `mdsplit` will not remove any files in your documentation directory. It will only create or update files.\nThis is meant to allow auxiliary files that you also want to be part of the documentation.\n\nHowever, that also means that if you change your section names in `README.md`, `mdsplit` will create a new file for this\nsection and the old file would be left untouched. Your GitHub pages would then show you the new and old sections.\n\nIf this is not an auxiliary file you want in your documentation, you need to remove these files.\n\nTo make it easier to identify external auxiliary files, after saving the new markdown files, `mdsplit` will look for\nany `.md` files in the `docs` directory. If there are any files not generated by `mdsplit`, it will emit a message like\nthe following:\n\n=== \"Output\"\n\n    ```console\n    # The following .md files were not generated by mdsplit\n    # Please make sure that is on purpose:\n    Outsider doc file: docs/README.md\n    Outsider doc file: docs/COMPLETE_GALLERY.md\n    ``` \n\nIf any of these files contain a comment indicating that `mdsplit` generated the file, then `mdsplit` might automatically\nremove the file. You can control this behaviour with the `--erase-old-mdsplit-files` (or `-e`) option. The default value\nis `true` so you need `--erase-old-mdsplit-files=false` to turn it off.\n\n## Installing\n\n### Binaries\n\nGet the latest release from the [Release Page](https://GitHub.com/alandefreitas/mdsplit/releases/) or download the\nlatest binaries from\nthe [CI Artifacts](https://github.com/alandefreitas/mdsplit/actions?query=workflow%3A%22Build+mdsplit%22+event%3Apush).\n\n### Install from Source\n\nTo install from the source files:\n\n=== \"Windows\"\n\n    ```bash\n    mkdir build\n    cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=\"/O2\"\n    cmake --build . -j 2 --config Release\n    cmake --install .\n    ```\n\n=== \"Linux\"\n\n    ```bash\n    mkdir build\n    cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=\"-O2\"\n    cmake --build . -j 2 --config Release\n    sudo cmake --install .\n    ```\n\n=== \"Mac OS\"\n\n    ```bash\n    mkdir build\n    cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=\"-O2\"\n    cmake --build . -j 2 --config Release\n    cmake --install .\n    ```\n\nThe dependencies are CMake 3.17 and C++17.\n\n## Gallery\n\nThese are some projects that use `mdsplit`. Use the links below to compare their documentation with the README.md files.\n\n| Repository      |     Documentation    |    README.md    |\n|-----------------|----------------------|-----------------|\n| Matplot++       | [URL](https://alandefreitas.github.io/matplotplusplus/) | [URL](https://github.com/alandefreitas/matplotplusplus/blob/master/README.md) |\n| Pareto    | [URL](https://alandefreitas.github.io/pareto/) | [URL](https://github.com/alandefreitas/pareto/blob/master/README.md) |\n| BibExplorer    | [URL](https://alandefreitas.github.io/bibexplorer/) | [URL](https://github.com/alandefreitas/bibexplorer/blob/master/README.md) |\n| mdsplit itself    | [URL](https://alandefreitas.github.io/mdsplit/) | [URL](https://github.com/alandefreitas/mdsplit/blob/master/README.md) |\n\n!!! note Let me know if you want to list your project here.\n\n## Contributing\n\n### Guidelines\n\nIf contributing with code, please leave the pedantic mode ON (` -DBUILD_WITH_PEDANTIC_WARNINGS=ON`),\nuse [cppcheck](http://cppcheck.sourceforge.net), and [clang-format](https://clang.llvm.org/docs/ClangFormat.html).\n\n\u003cdetails\u003e\n    \u003csummary\u003eExample: CLion\u003c/summary\u003e\n\n![CLion Settings with Pedantic Mode](./docs/images/pedantic_clion.png)\n\n\u003c/details\u003e\n\n### Contributors\n\n\u003c!-- readme: collaborators,contributors -start --\u003e \n\u003ctable\u003e\n\u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n        \u003ca href=\"https://github.com/alandefreitas\"\u003e\n            \u003cimg src=\"https://avatars0.githubusercontent.com/u/5369819?v=4\" width=\"100;\" alt=\"alandefreitas\"/\u003e\n            \u003cbr /\u003e\n            \u003csub\u003e\u003cb\u003eAlan De Freitas\u003c/b\u003e\u003c/sub\u003e\n        \u003c/a\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n        \u003ca href=\"https://github.com/actions-user\"\u003e\n            \u003cimg src=\"https://avatars1.githubusercontent.com/u/65916846?v=4\" width=\"100;\" alt=\"actions-user\"/\u003e\n            \u003cbr /\u003e\n            \u003csub\u003e\u003cb\u003eActions-user\u003c/b\u003e\u003c/sub\u003e\n        \u003c/a\u003e\n    \u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\u003c!-- readme: collaborators,contributors -end --\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falandefreitas%2Fmdsplit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falandefreitas%2Fmdsplit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falandefreitas%2Fmdsplit/lists"}