{"id":13624544,"url":"https://github.com/mistermicheels/markdown-notes-tree","last_synced_at":"2025-04-16T00:32:40.097Z","repository":{"id":41055538,"uuid":"230643883","full_name":"mistermicheels/markdown-notes-tree","owner":"mistermicheels","description":"Generate Markdown trees that act as a table of contents for a folder structure with Markdown notes","archived":false,"fork":false,"pushed_at":"2024-03-02T09:39:14.000Z","size":619,"stargazers_count":34,"open_issues_count":0,"forks_count":9,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-04-20T11:24:20.930Z","etag":null,"topics":["contents","docs","documentation","markdown","notes","table","table-of-contents","toc","toc-generator","tree"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/markdown-notes-tree","language":"JavaScript","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/mistermicheels.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2019-12-28T17:54:41.000Z","updated_at":"2024-06-18T09:30:47.959Z","dependencies_parsed_at":"2023-02-18T16:01:52.248Z","dependency_job_id":"93294ee8-e122-4529-bdc9-d2f3058216d0","html_url":"https://github.com/mistermicheels/markdown-notes-tree","commit_stats":{"total_commits":151,"total_committers":3,"mean_commits":"50.333333333333336","dds":0.0331125827814569,"last_synced_commit":"b0f72708d179119a5ff82ada70ed4f6ca0c74d52"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mistermicheels%2Fmarkdown-notes-tree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mistermicheels%2Fmarkdown-notes-tree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mistermicheels%2Fmarkdown-notes-tree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mistermicheels%2Fmarkdown-notes-tree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mistermicheels","download_url":"https://codeload.github.com/mistermicheels/markdown-notes-tree/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223691651,"owners_count":17186862,"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":["contents","docs","documentation","markdown","notes","table","table-of-contents","toc","toc-generator","tree"],"created_at":"2024-08-01T21:01:43.614Z","updated_at":"2024-11-08T13:30:40.749Z","avatar_url":"https://github.com/mistermicheels.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"Project status:\n\n-   ✅ Actively maintained\n-   🐢 Limited bandwidth\n-   🔒 Not looking for code contributions from other developers\n\n# markdown-notes-tree\n\n[![npm](https://img.shields.io/npm/v/markdown-notes-tree?style=flat)](https://www.npmjs.com/package/markdown-notes-tree)\n\nIf you have a folder structure with Markdown notes, you can use this tool to generate Markdown trees that act as a table of contents for the folder structure.\n\n[Example input and expected result](test-data/basics)\n\n[Real-life example](https://github.com/mistermicheels/learning-notes#readme)\n\nBy default, the tool does the following:\n\n-   Append a complete tree to the main `README.md` file (in the directory where the tool is executed)\n-   Write/overwrite `README.md` files in subdirectories, each containing the subdirectory's name as title and a tree of the subdirectory's contents (can be disabled through command line arguments)\n\nYou can run the tool again and again without changing the result. Once a tree has been written to your main `README.md` file, you can add anything below the tree (or move the tree) and the tool will respect the tree's boundaries.\n\nOf course, it is recommended to run the tool again every time you make changes to the Markdown notes in your folder structure. It can be useful to include the tool in build scripts or pre-commit hooks.\n\n## Install\n\n```\nnpm install -D markdown-notes-tree\n```\n\nNot using Node for your project? You can install `markdown-notes-tree` globally, or you can even add it as a [pre-commit plugin](https://pre-commit.com/#plugins).\n\nExample pre-commit configuration:\n\n```\nrepos:\n-   repo: https://github.com/mistermicheels/markdown-notes-tree\n    rev: v1.12.0\n    hooks:\n    -   id: markdown-notes-tree\n```\n\n## Use\n\nYou can run the tool by running `npx markdown-notes-tree` from the command line or invoking `markdown-notes-tree` from an npm script.\n\nMake sure to run the tool in the top-level directory of your Markdown notes folder structure.\n\n## Ignored files and folders\n\nBy default, the tool ignores:\n\n-   Folders starting with `.` or `_`\n-   `node_modules` folders\n-   Files that are not Markdown files\n\nYou can customize this using the `--ignore` and `--includeAllDirectoriesByDefault` command line arguments (see below).\n\n## Note titles from YAML front matter\n\nNormally, the tool expects to find the note's title as the first level 1 Markdown heading in the file.\n\nHowever, if a note starts with YAML front matter that has a `tree_title` attribute, the value of `tree_title` will be used as the note's title in the tree.\n\n## Subdirectory descriptions\n\nThe generated `README.md` files for subdirectories provide some space to add a description for the directory. If a description is provided, it will be preserved and it will also be included in generated trees containing the directory.\n\n## Subdirectory titles\n\nBy default, the generated `README.md` files for subdirectories use the subdirectory's name as title. If you change this into a custom title, that custom title will be preserved and it will be used in the tree instead of the name of the subdirectory.\n\n## Extra content in subdirectory README\n\nIf you add content to the generated `README.md` files for subdirectories before the title or between the title and the description, that content will be preserved. This could be useful for image headers etc.\n\n## Command line arguments\n\n### `--allowMissingTitle`\n\nDon't throw an error on missing title but instead use the file name as fallback.\n\nExample: `markdown-notes-tree --allowMissingTitle`\n\n### `--ignore`\n\nSpecify glob pattern for additional files or folders to ignore. You can use this argument multiple times in order to specify multiple glob patterns.\n\nExample: `markdown-notes-tree --ignore **/CONTRIBUTING.md`\n\nExample: `markdown-notes-tree --ignore CONTRIBUTING.md --ignore sub1/CONTRIBUTING.md`\n\nExample: `markdown-notes-tree --ignore exclude-this-folder`\n\n### `--includeAllDirectoriesByDefault`\n\nInclude all directories by default (don't apply the default ignored folders listed above). You can combine this with custom ignores as needed.\n\nExample: `markdown-notes-tree --includeAllDirectoriesByDefault --ignore node_modules`\n\n### `--includeUpwardNavigation`\n\nAdd \"Go one level up\" and \"Go to top level\" links at the top of subdirectory README files. If the `--linkToSubdirectoryReadme` option is enabled, these will link directly to README files. Otherwise, they will link to directories.\n\nNote: By design, `markdown-notes-tree` only ever touches the README files and not the actual notes. Upward navigation links will not be added to the notes.\n\nExample: `markdown-notes-tree --includeUpwardNavigation`\n\n### `--linkToSubdirectoryReadme`\n\nWhen linking to a subdirectory, link directly to its `README.md` file. Note that this assumes that each subdirectory will actually have a `README.md` file. By default, the tool generates these automatically.\n\nExample: `markdown-notes-tree --linkToSubdirectoryReadme`\n\n### `--noSubdirectoryTrees`\n\nDon't write `README.md` files to subdirectories. Any existing `README.md` files in subdirectories will be ignored.\n\nExample: `markdown-notes-tree --noSubdirectoryTrees`\n\n### `--notesBeforeDirectories`\n\nIf a directory contains both notes and subdirectories, put the notes before the subdirectories in he tree. By default, it's the other way around.\n\nExample: `markdown-notes-tree --notesBeforeDirectories`\n\n### `--numberSpaces`\n\nSpecify the number of spaces to use for indentation (the default is 4).\n\nExample: `markdown-notes-tree --numberSpaces 2`\n\n### `--orderNotesByTitle`\n\nOrder notes in the same (sub)directory by title instead of by filename.\n\nExample: `markdown-notes-tree --orderNotesByTitle`\n\n### `--readmeFilename`\n\nFilename to use for README files (both the main README file and subdirectory README files). The default is `README.md`.\n\nExample: `markdown-notes-tree --readmeFilename Home.md`\n\n### `--silent`\n\nDon't log to the console during execution.\n\nExample: `markdown-notes-tree --silent`\n\n### `--subdirectoryDescriptionOnNewLine`\n\nIf subdirectory descriptions are provided, put them on a new line in the tree.\n\nExample: `markdown-notes-tree --subdirectoryDescriptionOnNewLine`\n\n### `--useTabs`\n\nUse tabs (instead of the standard four spaces) for indentation.\n\nExample: `markdown-notes-tree --useTabs`\n\n## Known limitations\n\n-   The tool does not support Markdown links inside the titles of notes and subdirectory README files\n    -   This is intentional, because these titles will be turned into links by the tool and Markdown does not support nested links\n    -   As a workaround, HTML links can be used ([example](test-data/subdirectory-title-rich-text/expected/sub2/sub2b/README.md))\n-   Subdirectory descriptions can only be a single paragraph, nothing more\n\n## Development\n\nThis project is using Prettier to format the JavaScript code. Installing the VS Code plugin recommended through the `extensions.json` file should make this easy.\n\nThe build script verifies that the formatting actually matches Prettier style and that the unit and integration tests are passing.\n\nDuring development, you can run the tool on a folder by navigating to the folder in the command line and then executing `node path/to/cli.js`, adding arguments as needed. Example: `node ../../../cli.js --silent`\n\n### Markdown processing approach\n\n-   When examining existing Markdown, use actual parsed AST where possible\n-   For content generated by the tool, use AST for generation where practical\n    -   Complication: we need to retain some level of control over line endings, indentation, ...\n-   For user-maintained content, prefer reusing existing content instead of regenerating (the latter might change formatting syntax, for example `*` vs `_` for emphasis)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmistermicheels%2Fmarkdown-notes-tree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmistermicheels%2Fmarkdown-notes-tree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmistermicheels%2Fmarkdown-notes-tree/lists"}