Open abhi4578 opened 2 years ago
Examples
Feel free to extend this discussion here on this thread at everyone in datakaveri team
The markdown docs can be "beautified"/UX or UI themes through some sort of static site generator from markdown files(.md) , in docker they use jekyll static site generator. Its OSS licensed under MIT. Host it using github pages?
Its pretty much simple both for UI point of view and developers/anyone who wants to contribute to documentation by just clicking edit docs
. Its standard template markdown and edit the markdown files! The src markdown file
https://github.com/docker/docker.github.io/blob/master/get-started/overview.md corresponds to docs page is https://docs.docker.com/get-docker/! You can get much better idea of each page by going to that page in docker docs and clicking edit this page which would redirect to exact github src code of that page :)
Pros of hosting docs on github pages using jekyll:
Cons:
References:
It would be better if we know what exact content is to be hosted through website and other requirements of website -
versioned documentation - maybe not so straightforward as sphix/mkdocs in readthedocs . https://justwriteclick.com/2017/07/30/investigating-jekyll-for-versioned-content/
Some requirements from the meet on friday 12 Nov on documentation tool, how we start documenting:
tion of docs from markdown files. Eg: minimize use of liquid template in md files if we use jekyll tool
Please add more if i have forgotten something @mahimatics @ThorodanBrom @swaminathanvasanth @abhisekparichha-iudx @Rnaaz @kailash @rraks Feel free to discuss here the tools in this issue thread!
Docusaurus is another powerful open source static-site generator which can help to build a beautiful documentation site in no time. It builds a single-page application with a fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features, but can also be used to create any kind of site. Some of it's key features:
Sharing the links for the above. Please feel free to share your views & feedback.
https://docusaurus.io/docs https://www.youtube.com/watch?v=I-hYKNgaMmE https://docusaurus.io/
Also sharing the screenshots which I have edited using Docusaurus.
Maintain uniform structure, git version documentation just like a code, mainly because docs will change with code changes and releases!
Structure the documentation , according to needs