0

Can I write documentation in multiple .md files that reference each other and then use a tool like Dillinger to turn all these .md files into multiple html pages referencing each other?

I.e. can I go automatically (using Dillinger or Stackedit or any other software) from

docs/readme.md  (with links to feature1.md and details.md)
docs/features/feature1.md (with link to readme.md)
src/details.md (with link to readme.md)

to

docs/readme.html (with links to feature1.html and details.html)
docs/features/feature1.html (with link to readme.html)
src/details.html (with link to readme.html)

So that I can build and maintain online documentation on a piece of software I write, with the expectation that the user can access the doc by either:

  • reading directly the .md file inserted in my source, or,

  • visualizing on their browser the html documentation I will have generated from the .md files whenever I release/update my software

Lolo
  • 3,935
  • 5
  • 40
  • 50
  • Sounds like you are looking for a [static site generator](https://www.staticgen.com/). Markdown doesn't update links from `.md` to `.html` itself, but many static site generators do on top of Markdown. – Waylan Jun 12 '19 at 14:39
  • Can you clarify a couple of things? 1. with the static site generators I see, you point to all your md files from one config file (.js or .yaml) and the site you build provides a way to navigate to your various auto-generated html pages. Are you saying you can alter that process to generate pages that can reference each other? How? 2. All these static sites being generated need to be served by a local or remote server. Can't SS generators ever create a set of html pages that can directly be navigated in a browser without the need to run a local server? – Lolo Jun 12 '19 at 21:56
  • Many SSG can meet all of those concerns. However, that is generally not the default. Regarding navigating in a browser without a local file server, that will work for basic HTML, but it starts to fall down when more complicated stuff (JavaScript) due to browser security restrictions. Therefore the default is to assume you are using server to get the full feature set. But if you don't need those advanced features (and use a theme which doesn't include them), then that won't matter to you. – Waylan Jun 12 '19 at 23:05

1 Answers1

0

mkdocs using the use_directory_urls: false option does exactly that when running mkdocs build

Lolo
  • 3,935
  • 5
  • 40
  • 50