Process #1

New Issue

We need to figure out a sustainable process for this new documentation.

I would prefer keeping the docs in the main repo, a low barrier to entry is (imo) extremely important for people contributing to docs. Docs are somehow always
a. the lowest hanging fruit for contributions, yet
b. one of the least contributed-to facets of a project
With that in mind, I don't think we can get around some minor hackery to extract the docs from the main repo into something docusaurus can use.
- Looking at Woodpecker, we have a dedicated docs folder for old versions, which imo isn't ideal

My initial thought is to convert all the docs in the main repo to simple markdown files (with frontmatter, presumably), or more simply something that you could theoretically copy/paste into docusaurus and it would "just work" assuming the config is set up correctly here.

I by no means have this all the way thought out, so feedback is very welcome!

We need to figure out a sustainable process for this new documentation. 1. I would prefer keeping the docs in the main repo, a low barrier to entry is (imo) extremely important for people contributing to docs. Docs are somehow always a. the lowest hanging fruit for contributions, yet b. one of the least contributed-to facets of a project 2. With that in mind, I don't think we can get around some minor hackery to extract the docs from the main repo into something docusaurus can use. - Looking at Woodpecker, we have a dedicated docs folder for old versions, which imo isn't ideal --- My initial thought is to convert all the docs in the main repo to simple markdown files (with frontmatter, presumably), or more simply something that you could theoretically copy/paste into docusaurus and it would "just work" assuming the config is set up correctly here. --- I by no means have this all the way thought out, so feedback is very welcome!

A agree with your assessment re: reasons to keep docs in the main repo, hence why I have the CI converting the docs from the main repo into a format acceptable by docusaurus.

This approach means that we can, in the future, have tea cli, act_runner, and other related tools have docs in their specific repo, and then pull them all together into this one site. Additionally, we can still keep the docs in a hugo acceptable format and build/bundle the docs on gitea build/release.

A agree with your assessment re: reasons to keep docs in the main repo, hence why I have the CI converting the docs from the main repo into a format acceptable by docusaurus. This approach means that we can, in the future, have tea cli, act_runner, and other related tools have docs in their specific repo, and then pull them all together into this one site. Additionally, we can still keep the docs in a hugo acceptable format and build/bundle the docs on gitea build/release.

I hadn't thought of adding docs from other repos, but that would also be great!

wrt hugo-compatible, the reason I wanted to start this discussion was to figure out whether we wanted to deal with all of the idiosyncrasies of Hugo and Docusaurus vs simplifying the Docu ingestion process and going all-in.

The shell scripts here work (and again a huge thank you for that), so there's certainly no rush, but would it be easier to maintain if we no longer had to worry about Hugo at all?

I hadn't thought of adding docs from other repos, but that would also be great! wrt hugo-compatible, the reason I wanted to start this discussion was to figure out whether we wanted to deal with all of the idiosyncrasies of Hugo _and_ Docusaurus vs simplifying the Docu ingestion process and going all-in. The shell scripts here work (and again a huge thank you for that), so there's certainly no rush, but would it be easier to maintain if we no longer had to worry about Hugo at all?

A agree with your assessment re: reasons to keep docs in the main repo, hence why I have the CI converting the docs from the main repo into a format acceptable by docusaurus.

This approach means that we can, in the future, have tea cli, act_runner, and other related tools have docs in their specific repo, and then pull them all together into this one site. Additionally, we can still keep the docs in a hugo acceptable format and build/bundle the docs on gitea build/release.

I don't think we need always to keep compatible with hugo. I mean, once the new docs site ready, we can change main repositories docs as a docusaurus folder directly. Since docusaurus supports mono repos, so it's a good idea to merge all documentation as in one. But we need to consider about the webhooks. How to and when update this docs site?

> A agree with your assessment re: reasons to keep docs in the main repo, hence why I have the CI converting the docs from the main repo into a format acceptable by docusaurus. > > This approach means that we can, in the future, have tea cli, act_runner, and other related tools have docs in their specific repo, and then pull them all together into this one site. Additionally, we can still keep the docs in a hugo acceptable format and build/bundle the docs on gitea build/release. I don't think we need always to keep compatible with hugo. I mean, once the new docs site ready, we can change main repositories docs as a docusaurus folder directly. Since docusaurus supports mono repos, so it's a good idea to merge all documentation as in one. But we need to consider about the webhooks. How to and when update this docs site?