Ask HN: What are you using for public documentation these days?

#1

Post by vital101 » Thu, Nov 18, 2021, 11:43 AM UTC

On a new side project I'm working on I need to have a fair amount of documentation for usage, implementation, options, etc. In the past I've used https://docsify.js.org hosted on Vercel, but I was curious if there is anything else out there people like. Looking for free or paid options. So long has I can host on a subdomain I'm indifferent.

Thanks!

Re: Ask HN: What are you using for public documentation these days?

#2

Post by austincheney » Thu, Nov 18, 2021, 12:06 PM UTC

I am frequently working on ways to document inline with the code using comments and then extract those comments during the build process to keep documentation up to date automatically. The comments are formatted as mark down so that they may be converted from code comments to stand alone mark down documents.

I have also noticed that in VS Code a comment immediately preceding a type or interface declaration written in mark down format becomes formatted markdown in the tooltip where that type is used.

Re: Ask HN: What are you using for public documentation these days?

#3

Post by plondon514 » Thu, Nov 18, 2021, 12:07 PM UTC

Using https://docusaurus.io/ for my side project codeamigo. It’s been great, although arguably I need to add more to the docs :)

Re: Ask HN: What are you using for public documentation these days?

#4

Post by stichers » Thu, Nov 18, 2021, 12:13 PM UTC

Basic markdown and Sphinx to build into HTML, publishing via github pages. It's an open source project so putting the docs alongside the code just makes sense. Although Sphinx isn't great for my money, it gets the job done.

Re: Ask HN: What are you using for public documentation these days?

#5

Post by dabeeeenster » Thu, Nov 18, 2021, 12:14 PM UTC

We [1] moved from mkdocs to docusaurus v2 and couldnt be happier. Very active project with a great community, and enough flexibility and config overrides when we need it.

[1] https://docs.flagsmith.com/

Re: Ask HN: What are you using for public documentation these days?

#6

Post by tomw1808 » Thu, Nov 18, 2021, 12:24 PM UTC

I'm using mkdocs with the material plugins [1]. I'm running it mainly for a Blockchain Education site for my labs from my course, which seems to be fine [2].

I did a fair amount of customization though, so I am running all this as mkdocs plugins, not directly from the materials project.

[1] https://squidfunk.github.io/mkdocs-material/ [2] https://ethereum-blockchain-developer.com

Re: Ask HN: What are you using for public documentation these days?

#7

Post by byteface » Thu, Nov 18, 2021, 12:25 PM UTC

stichers wrote: post #4

Basic markdown and Sphinx to build into HTML, publishing via github pages. It's an open source project so putting the docs alongside the code just makes sense. Although Sphinx isn't great for my money, it gets the job done.

I also use sphinx and https://readthedocs.org/. lots of sphinx repos are open source so you can use them for inspiration... https://www.sphinx-doc.org/en/master/examples.html

Re: Ask HN: What are you using for public documentation these days?

#8

Post by perfopt » Thu, Nov 18, 2021, 12:25 PM UTC

Is there anything that supports languages other than English - specifically Indian languages. I am writing documentation (book) to be distributed online. I presently use mdbook but markdown does not support anything other than English.

Re: Ask HN: What are you using for public documentation these days?

#9

Post by woudsma » Thu, Nov 18, 2021, 12:25 PM UTC

As others in this thread have mentioned, Docusaurus is really good. It was very easy to add search with Algolia and meta tags for SEO as well.

Re: Ask HN: What are you using for public documentation these days?

#10

Post by krish888 » Thu, Nov 18, 2021, 12:27 PM UTC

Stoplight.io