docusaurus site for docs?

[andrewm4894]

trafficstars

might be overkill for now but on the other hand is very easy to get up and running and maybe easier to do now (and evolve sanely overtime) rather than later (i'd be able and happy to help as have used docusaurus for my work: https://learn.netdata.cloud/, https://blog.netdata.cloud/).

https://github.com/facebook/docusaurus https://docusaurus.io/docs/deployment#deploying-to-github-pages

could probably host it on github pages or via netlify very easy too.

[yk]

what would be the required steps for us? what would go in there, the docs/ pages?

[andrewm4894]

docs can still live in /docs as markdown files so easy to work on for anyone.

just some extra docusarus specific config stuff and a github action then to deploy what's in /docs to a github page.

so could start with as minimal or flat/obvious a structure as possible and just sort of package up something very similar to existing .md files (will a little bit of a frontmatter header on them).

i probably could bash together a POC in a branch on my fork easy enough.

[andrewm4894]

here is a branch with a default docusarus starter https://github.com/andrewm4894/Open-Assistant/tree/docs-site-poc

deployed to github pages here: https://andrewm4894.github.io/Open-Assistant/

github.io domain in reality would be https://LAION-AI.github.io/Open-Assistant/ but easy to get a custom domain too if wanted.

[andrewm4894]

actually wait thats just default gh pages boiler - will need to do one or two little things to get it using docusaurus

[yk]

sounds good! if you or someone else wants to take this on, all clear :)

[andrewm4894]

made draft pr here: https://github.com/LAION-AI/Open-Assistant/pull/346

will work on it a little and ping when something ready to look at - 90% sure is easy enough and could be useful while also very minimal friction or overhead for contribution and changes.

basic moving parts:

• /docs is now a docusaurus project (https://github.com/andrewm4894/Open-Assistant/tree/docs-site-poc/docs)
• gh action to deploy docs site to gh-pages branch (https://github.com/andrewm4894/Open-Assistant/blob/docs-site-poc/.github/workflows/deploy-docs-site.yaml)
• gh pages then just deploys from the gh-pages branch (https://github.com/andrewm4894/Open-Assistant/tree/gh-pages) eg its just the static site to be deployed (created/updated by gh action above).

Can see example here: https://andrewm4894.github.io/Open-Assistant/

I have ported existing .md files into folders to show how it works. For example i put all the data related md files in here: https://github.com/andrewm4894/Open-Assistant/tree/docs-site-poc/docs/docs/data

and you end up with something like this:

basically docusaurus uses folders to build/infer the sidebar, some metadata in the md files can be used by docusarus. And then its mostly just some easy config changes to do 90% of what you typically want in a docs site.

lastly i left some existing DUMMY tutorial sections in there to show some further examples. also easy enough to add some css and styling, i have not attempted any of that yet (no idea on css and stuff like that).

[fozziethebeat]

Docusaurus is great.

🦖

[jjmachan]

I think this is complete? we can close this issue, right? or is there anything else left to address