{"id":15130908,"url":"https://github.com/joakin/markdown-folder-to-html","last_synced_at":"2025-04-07T07:15:04.210Z","repository":{"id":9812861,"uuid":"63423279","full_name":"joakin/markdown-folder-to-html","owner":"joakin","description":"Convert a folder with files and markdown documents to an HTML site","archived":false,"fork":false,"pushed_at":"2023-03-08T15:21:37.000Z","size":323,"stargazers_count":122,"open_issues_count":20,"forks_count":36,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-31T06:03:41.965Z","etag":null,"topics":["cli","html","markdown","node"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joakin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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":"2016-07-15T13:17:26.000Z","updated_at":"2024-07-31T20:49:14.000Z","dependencies_parsed_at":"2024-06-18T16:35:51.972Z","dependency_job_id":null,"html_url":"https://github.com/joakin/markdown-folder-to-html","commit_stats":{"total_commits":108,"total_committers":4,"mean_commits":27.0,"dds":0.04629629629629628,"last_synced_commit":"289a0c9cf7b1fd0dd048b77f364fb306a2ddae3c"},"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joakin%2Fmarkdown-folder-to-html","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joakin%2Fmarkdown-folder-to-html/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joakin%2Fmarkdown-folder-to-html/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joakin%2Fmarkdown-folder-to-html/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joakin","download_url":"https://codeload.github.com/joakin/markdown-folder-to-html/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247608153,"owners_count":20965952,"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":["cli","html","markdown","node"],"created_at":"2024-09-26T03:08:25.870Z","updated_at":"2025-04-07T07:15:04.042Z","avatar_url":"https://github.com/joakin.png","language":"TypeScript","readme":"# markdown-folder-to-html\n\nSimplest zero-config way to generate html docs from markdown files.\n\nCopies `docs` to `_docs` and compiles markdown files to html using\n`docs/template.html`.\n\n[Live example at chimeces.com/markdown-folder-to-html](http://chimeces.com/markdown-folder-to-html/)\n\n## Usage\n\nRequires node.js \u003e= 6\n\nGiven we have some docs:\n\n1. `mkdir -p docs`\n2. Add some docs `echo \"**Banana**\" \u003e docs/banana.md`\n3. Add some docs `echo \"**Apple**\" \u003e docs/index.md`\n\n### In a project\n\n1. Install `npm install -D markdown-folder-to-html`\n2. Add `docs` to npm scripts `{\"scripts\": {\"docs\": \"markdown-folder-to-html\"}}`\n3. 🎉 `npm run docs` and `open _docs/index.html`\n\n### Globally\n\n1. Install `npm install -g markdown-folder-to-html`\n2. 🎉 `markdown-folder-to-html` and `open _docs/index.html`\n\n## Conventions\n\n### Input/Output folder\n\nYou can pass an argument to the cli to change the input folder (by default\n`docs`). That will change the output folder too to `_FOLDERNAME` (by default\n`_docs`).\n\n```bash\nmarkdown-folder-to-html documentation\n# Outputs site to _documentation\n```\n\nIf you want to change the output folder name, just `mv` it to something else.\n\n### Custom HTML\n\nThe default HTML is extremely basic, but\n[simple and pretty](https://github.com/joakin/markdown-folder-to-html/blob/master/docs/template.html),\nand is the one used in the docs.\n\nThis is the basic template that would work:\n\n```html\n\u003c!doctype html\u003e\n\u003chtml\u003e\n\u003cbody\u003e\n\u003cnav\u003e\n\t\u003c!--NAV--\u003e\n\u003c/nav\u003e\n\u003carticle\u003e\n\t\u003c!--CONTENT--\u003e\n\u003c/article\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\nCreate your own in your docs folder `docs/template.html` to use that one\ninstead. Feel free to include styles inline or CSS files (since all will be\ncopied to output).\n\n### Order\n\nYou may have noticed that files are sorted alphabetically. There's a little\ntrick where if you name your folders/files with XX-folder/XX-file (XX being a\nnumber of 1+ digits) those numbers won't show up on the index of the pages,\ngiving you the ability to organize files both in the filesystem and in the\ngenerated HTML site.\n\nAlso, the root `index.md` file will always show up at the beginning of the\nindex.\n\n### Site contents and information for custom templates\n\nIf you want to do things with a custom template HTML you need the information of\nthe site. This will allow you to do things in the front-end UI, like adding\nsearch to the static site with lunrjs or other things like adding buttons for\nthe next/previous article.\n\nFor this use cases, you will see a `contents.json` generated in your output\nfolder. It contains the hierarchical paths of the files, and the contents with\nthe original markup, the HTML, the original path and the transformed URL:\n\n```json\n{\n  \"paths\": [\n    {\n      \"type\": \"file\",\n      \"value\": \"index.md\"\n    },\n    {\n      \"type\": \"file\",\n      \"value\": \"1-banana.md\"\n    },\n    {\n      \"type\": \"dir\",\n      \"name\": \"a-folder\",\n      \"children\": [\n        {\n          \"type\": \"file\",\n          \"value\": \"a-folder/with-a-post.md\"\n        }\n      ]\n    }\n    //...\n  ],\n  \"contents\": [\n    {\n      \"path\": \"index.md\",\n      \"url\": \"index.html\",\n      \"content\": \"# markdown-folder-to-html\\n\\nSimplest zero-config ...\",\n      \"html\": \"\u003ch1\u003emarkdown-folder-to-html\u003c/h1\u003e\\n\u003cp\u003eSimplest zero-config ...\",\n      \"id\": 0\n    },\n    {\n      \"path\": \"1-banana.md\",\n      \"url\": \"1-banana.html\",\n      \"content\": \"**Banana**\\n\\nYou can have [nested folders](./n...\",\n      \"html\": \"\u003cp\u003e\u003cstrong\u003eBanana\u003c/strong\u003e\u003c/p\u003e\\n\u003cp\u003eYou can have \u003ca h...\",\n      \"id\": 1\n    }\n    //...\n  ]\n}\n```\n\nSee the [JSON file](https://chimeces.com/markdown-folder-to-html/contents.json)\nof our documentation site for an example.\n\nYou can then fetch this JSON file with JS from your template, and go crazy with\nit, processing the contents to adapt them for search, looking for the\nprevious/next articles to link to them, etc.\n\nIf you have working examples of a template that does something interesting,\nplease let me know and I'll list them here!\n\n## Why\n\nAfter quite a lot of research, I couldn't find a simple and straightforward\nsolution to generating html docs from a folder full of markdown files that\nrelied on simple concepts. That is what this tool does:\n\n- Simply copy everything over, and translate .md files to .html with a pure HTML\n  layout (feel free to add CSS, or JS, or precompile those assets if you need\n  to)\n- .md links are rewritten to .html so that you can reference files with their\n  real path on your markdown files and they'll work on the HTML version too.\n- Provide sensible defaults and zero-configuration. JUST WORK.\n- Use know abstraction, like the file system, pure HTML, etc\n\n## Links\n\n- https://github.com/joakin/markdown-folder-to-html\n- https://npmjs.org/package/markdown-folder-to-html\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoakin%2Fmarkdown-folder-to-html","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoakin%2Fmarkdown-folder-to-html","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoakin%2Fmarkdown-folder-to-html/lists"}