{ "paths": [ { "type": "file", "value": "index.md" }, { "type": "file", "value": "1-banana.md" }, { "type": "dir", "name": "a-folder", "children": [ { "type": "file", "value": "a-folder/with-a-post.md" } ] }, { "type": "dir", "name": "nested", "children": [ { "type": "file", "value": "nested/another-banana.md" }, { "type": "file", "value": "nested/index.md" }, { "type": "file", "value": "nested/so_apple.md" }, { "type": "dir", "name": "vegetables", "children": [ { "type": "file", "value": "nested/vegetables/others.md" } ] } ] }, { "type": "dir", "name": "tests", "children": [ { "type": "file", "value": "tests/issue16.md" } ] } ], "contents": [ { "path": "index.md", "url": "index.html", "content": "# 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 >= 6\n\nGiven we have some docs:\n\n1. `mkdir -p docs`\n2. Add some docs `echo \"**Banana**\" > docs/banana.md`\n3. Add some docs `echo \"**Apple**\" > 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\n\n\n\n
\n\t\n
\n\n\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\": \"

markdown-folder-to-html

\\n

Simplest 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\": \"

Banana

\\n

You can have markdown-folder-to-html\n

Simplest zero-config way to generate html docs from markdown files.

\n

Copies docs to _docs and compiles markdown files to html using\ndocs/template.html.

\n

Live example at chimeces.com/markdown-folder-to-html

\n

Usage

\n

Requires node.js >= 6

\n

Given we have some docs:

\n
    \n
  1. mkdir -p docs
  2. \n
  3. Add some docs echo "**Banana**" > docs/banana.md
  4. \n
  5. Add some docs echo "**Apple**" > docs/index.md
  6. \n
\n

In a project

\n
    \n
  1. Install npm install -D markdown-folder-to-html
  2. \n
  3. Add docs to npm scripts {"scripts": {"docs": "markdown-folder-to-html"}}
  4. \n
  5. 🎉 npm run docs and open _docs/index.html
  6. \n
\n

Globally

\n
    \n
  1. Install npm install -g markdown-folder-to-html
  2. \n
  3. 🎉 markdown-folder-to-html and open _docs/index.html
  4. \n
\n

Conventions

\n

Input/Output folder

\n

You can pass an argument to the cli to change the input folder (by default\ndocs). That will change the output folder too to _FOLDERNAME (by default\n_docs).

\n
markdown-folder-to-html documentation\n# Outputs site to _documentation\n
\n

If you want to change the output folder name, just mv it to something else.

\n

Custom HTML

\n

The default HTML is extremely basic, but\nsimple and pretty,\nand is the one used in the docs.

\n

This is the basic template that would work:

\n
<!doctype html>\n<html>\n<body>\n<nav>\n\t<!--NAV-->\n</nav>\n<article>\n\t<!--CONTENT-->\n</article>\n</body>\n</html>\n
\n

Create 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

Order

\n

You 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

Also, the root index.md file will always show up at the beginning of the\nindex.

\n

Site contents and information for custom templates

\n

If 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

For 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  "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": "<h1>markdown-folder-to-html</h1>\\n<p>Simplest 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": "<p><strong>Banana</strong></p>\\n<p>You can have <a h...",\n      "id": 1\n    }\n    //...\n  ]\n}\n
\n

See the JSON file\nof our documentation site for an example.

\n

You 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

If you have working examples of a template that does something interesting,\nplease let me know and I’ll list them here!

\n

Why

\n

After 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

Links

\n\n", "id": 0 }, { "path": "1-banana.md", "url": "1-banana.html", "content": "**Banana**\n\nYou can have [nested folders](./nested/index.md)\n\nWe also have [another banana](./nested/another-banana.md)\n\nAnd GFM features like tables:\n\n| Hello | World |\n| :-- | --: |\n| Yes | 1 |\n\n\nAnd automatic links https://example.com", "html": "

Banana

\n

You can have nested folders

\n

We also have another banana

\n

And GFM features like tables:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n
HelloWorld
Yes1
\n

And automatic links https://example.com

\n", "id": 1 }, { "path": "a-folder/with-a-post.md", "url": "a-folder/with-a-post.html", "content": "This is a test post!!\n\n| Hi| Ho|\n|---|---|\n|let's|go|\n\nThis has a [code inside the `the link`](#woot). This is madness.\n\n![be happy](./tenor.gif)", "html": "

This is a test post!!

\n\n\n\n\n\n\n\n\n\n\n\n\n\n
HiHo
let’sgo
\n

This has a code inside the the link. This is madness.

\n

\"be

\n", "id": 2 }, { "path": "nested/another-banana.md", "url": "nested/another-banana.html", "content": "# Nested banana\n\nLorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus non luctus\njusto. Praesent a molestie quam. Quisque pulvinar arcu nec sem tincidunt, in\ndictum lectus eleifend. Quisque tincidunt tristique tortor a imperdiet. Proin\npharetra scelerisque venenatis. Donec tortor ante, aliquam eu lacinia eu,\ngravida sed neque. Sed vel felis facilisis, eleifend nisl sit amet, convallis\nturpis. Donec ultrices leo ac eros tristique, vel condimentum lorem interdum.\n\nAenean vel aliquet orci. Duis et risus ut metus accumsan consectetur. Nullam\nquis nisi facilisis, consectetur metus vitae, tempus purus. Fusce iaculis\ntincidunt nibh, in ornare quam congue vitae. Nulla commodo nulla eget ornare\nfaucibus. Sed a est eget sapien lobortis sollicitudin. Aliquam aliquam nisl id\ngravida dignissim. Sed placerat leo vitae eleifend aliquam. Sed facilisis\nultrices condimentum.\n\nPellentesque sed mollis eros. Pellentesque mollis ac ex ut tincidunt. Cras quis\nsuscipit tellus. Praesent vehicula vehicula sagittis. Ut id libero dui. Nunc\negestas ac urna vitae cursus. Nulla dictum sed est ut bibendum. Nam in magna\npulvinar, tincidunt felis ut, pulvinar erat. Cras velit leo, molestie eu ex\nvitae, interdum iaculis nisi. Cras congue felis vitae interdum fermentum. Donec\npulvinar nunc metus, a vulputate lorem suscipit in. Praesent semper felis ut\nenim suscipit, in pretium lectus consectetur. Curabitur sed leo suscipit augue\nconsequat finibus sit amet id lorem. Aliquam erat volutpat. Integer quis nulla\ntortor. Proin et aliquet sapien.\n\nNunc ac imperdiet tortor. Nunc justo magna, consequat sed dignissim vel,\nfermentum a nulla. Pellentesque sed fringilla velit, eu varius risus. Nam\nelementum justo finibus auctor tristique. Ut bibendum enim vitae elit aliquam\nvestibulum. Pellentesque varius eget sem quis fringilla. Nam vulputate purus\nvel rhoncus laoreet. Nam fermentum elementum diam, sed molestie purus. \n", "html": "

Nested banana

\n

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus non luctus\njusto. Praesent a molestie quam. Quisque pulvinar arcu nec sem tincidunt, in\ndictum lectus eleifend. Quisque tincidunt tristique tortor a imperdiet. Proin\npharetra scelerisque venenatis. Donec tortor ante, aliquam eu lacinia eu,\ngravida sed neque. Sed vel felis facilisis, eleifend nisl sit amet, convallis\nturpis. Donec ultrices leo ac eros tristique, vel condimentum lorem interdum.

\n

Aenean vel aliquet orci. Duis et risus ut metus accumsan consectetur. Nullam\nquis nisi facilisis, consectetur metus vitae, tempus purus. Fusce iaculis\ntincidunt nibh, in ornare quam congue vitae. Nulla commodo nulla eget ornare\nfaucibus. Sed a est eget sapien lobortis sollicitudin. Aliquam aliquam nisl id\ngravida dignissim. Sed placerat leo vitae eleifend aliquam. Sed facilisis\nultrices condimentum.

\n

Pellentesque sed mollis eros. Pellentesque mollis ac ex ut tincidunt. Cras quis\nsuscipit tellus. Praesent vehicula vehicula sagittis. Ut id libero dui. Nunc\negestas ac urna vitae cursus. Nulla dictum sed est ut bibendum. Nam in magna\npulvinar, tincidunt felis ut, pulvinar erat. Cras velit leo, molestie eu ex\nvitae, interdum iaculis nisi. Cras congue felis vitae interdum fermentum. Donec\npulvinar nunc metus, a vulputate lorem suscipit in. Praesent semper felis ut\nenim suscipit, in pretium lectus consectetur. Curabitur sed leo suscipit augue\nconsequat finibus sit amet id lorem. Aliquam erat volutpat. Integer quis nulla\ntortor. Proin et aliquet sapien.

\n

Nunc ac imperdiet tortor. Nunc justo magna, consequat sed dignissim vel,\nfermentum a nulla. Pellentesque sed fringilla velit, eu varius risus. Nam\nelementum justo finibus auctor tristique. Ut bibendum enim vitae elit aliquam\nvestibulum. Pellentesque varius eget sem quis fringilla. Nam vulputate purus\nvel rhoncus laoreet. Nam fermentum elementum diam, sed molestie purus.

\n", "id": 3 }, { "path": "nested/index.md", "url": "nested/index.html", "content": "This is the index file inside a folder.\n\nThe heading should link here.\n", "html": "

This is the index file inside a folder.

\n

The heading should link here.

\n", "id": 4 }, { "path": "nested/so_apple.md", "url": "nested/so_apple.html", "content": "# Apple\n\nSo delicious!\n\n", "html": "

Apple

\n

So delicious!

\n", "id": 5 }, { "path": "nested/vegetables/others.md", "url": "nested/vegetables/others.html", "content": "This is getting out of hand...\n", "html": "

This is getting out of hand…

\n", "id": 6 }, { "path": "tests/issue16.md", "url": "tests/issue16.html", "content": "Hello\n\n```\n'$KEY$' => $VALUE$,\n```\n\nThis breaks down the rendering?\n", "html": "

Hello

\n
'$KEY$' => $VALUE$,\n
\n

This breaks down the rendering?

\n", "id": 7 } ] }