Https://docs.particular.net - How to generate a local website with the whole doc?

1

Hi,

I’m learning NServiceBus for the moment but I’m often offline, and I’d like to get the documentation
https://docs.particular.net/ in local on my laptop.

Of course I could use a bot that scraps the website, but that’s the fallback option.

As the doc source is on https://docs.particular.net, I wonder how the HTML doc is generated ?
Is is done using MKDocs ? Docsify ? Couscous! ? other ???

Is there someone that can explain a bit the way to do ?

Tkx,

Eric

2

Hi Eric,

Our documentation uses a completely custom engine to turn the contents of our documentation repository into the site you see at https://docs.particular.net. The actual Markdown processor we use is Markdig but there are a lot of custom extensions to do things like:

  • Generate multiple versions of each page
  • Create Bootstrap alert boxes from annotations in the Markdown
  • Insert snippets from compiled projects (also by version) so that we can verify that code snippets compile
  • Insert includes that can be used across multiple pages
  • Insert partials that allow text to be different on different versions of the same page
  • Create zip archives for samples and tutorials, including generating *.suo files on the fly that set the correct startup projects for the solution
  • Generate headers with anchors that can be deep-linked
  • Render mermaid diagrams
  • I’m sure I’m forgetting stuff

It’s also not a static site like you’d create with tools like Jekyll or Hexo or Metalsmith. The site is served by a Nancy app that mostly just serves static content, but also adds the search capability. When we update the documentation repository, a webhook tells the engine that it’s time to rebuild and redeploy the site content.

So unfortunately, it’s not something that can be easily replicated.

The only current way to have our documentation available offline is probably to clone the repo and look at the files directly. Of course, that way you miss out on having the pages all stitched together with their proper partials and includes and code snippets.

It’s an interesting idea to provide a better way to make the content available offline. We’ll have to look into it.

-David

3

I’m happy to hear from you that my question is interesting, I’m disappointed that there is not a quick’n easy answer.

Anyway, cloning the repo sounds fine workaround, and using a Markdown editor should help.

Looking forward to discover a nice “Download Doc for Offline usage” on you doc website :slight_smile:

Eric