Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

news.ycombinator.com

Post reply on HN
Print view View original

61–70 of 111 posts

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

#61

Post by navaneethpk »

dsmmcken wrote: post #58
navaneethpk wrote: post #20

Earlier quoted context omitted.

It comes out of the box. We are now trying to figure out how to switch screenshots based on the light/dark mode. The screenshots taken from light mode of ToolJet looks odd in Docusaurus' dark mode.

You could build your own react image wrapper then use that component in the mdx and pass in two images, then display the appropriate one based on the current theme provider. Docusaurus makes using inline react components easy. You could also write your own remark plugin, that does it for you, and would have the benefit of having more control over what happens on the github side if it was still standard markdown.

Thanks, I will try creating a custom react component for handling the modes.

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

#62

Post by jomar »

A small Perl script https://github.com/jmarshall/manconvert> that grinds a subset of man page nroff syntax directly into HTML. (That subset being “the constructs that are used in the man pages that it's used on”.)

Some of the styling could be improved (those section headings for one!), but IMHO it produces better results than other more general-purpose manpage to HTML converters: see e.g. https://www.htslib.org/doc/samtools.html>.

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

#63

Post by eatonphil »

A markdown generator embeds markdown from a Github repo into the marketing site. This way the marketing site is kept private while anyone can easily contribute to docs.

Docs are kept in separate folders for each release.

https://github.com/multiprocessio/datastation-documentation

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

#66

Post by dsmmcken »

daviesliu wrote: post #36
navaneethpk wrote: post #15

We are using Docusaurus ( https://docusaurus.io/ ). - it is easy to configure/customise - looks really great out of the box - solid documentation - fast In our case, we just had to change the colors and font. Here is our Docusaurus code if that's helpful: https://github.com/ToolJet/ToolJet/tree/develop/docs and here is the live documentation: https://docs.tooljet.com/

Docusaurus is great! We migrated from Sphinx to Docusaurus[1] recently, the navigation is much better than before. One thing that bothers us: we have not figure a way to name the anchor that both work in Github (` `) and Docusaurus (`{#aws-s3}`), for example [2]. Any ideas? [1] https://juicefs.com/docs/community/introduction [2] https://github.com/juicedata/juicefs/blob/main/docs/en/how_t...

Not a great solution, but you could create the links github style, then write a remark/rehype plugin that transforms them to Docusaurus style at build time. I would probably just live with it though.

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

#67

Post by navaneethpk »

dsmmcken wrote: post #55
navaneethpk wrote: post #27

Earlier quoted context omitted.

You are right, placing the navigation on the sidebar is more useful than the links to GitHub and Slack.

Update to a more recent version, they re-worked the nav to be one menu on mobile.

Your comment was super helpful. I just tried upgrading to 2.0.0-beta.9. The menu now looks great on mobile. The upgrade is causing some other issues, will fix those and deploy the docs. Thanks!

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

#69

Post by gk1 »

We use Redoc.ly (https://www.redoc.ly) which has both a self-hosted and a managed version. I like that it integrates with GitHub, generates API Reference docs based on OpenAPI specs. It also has a "developer portal" for user guides, generated from markdown. All-in-all makes it easy to publish great-looking docs.

Preview: https://www.pinecone.io/docs/

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

#70

Post by rahimnathwani »

auspex wrote: post #68

Anyone know of a good hosted documentation that allows you to password protect the docs for a startup? (We don’t want public documentation and want to control access per user)

You can use whatever documentation software you want, and let the web server handle access control:

https://docs.nginx.com/nginx/admin-guide/security-controls/c...

You can Google 'nginx reverse proxy authentication' to find guides.

Post reply on HN