Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rearchitect documentation generator from markdown #1429

Closed
Racer159 opened this issue Mar 10, 2023 · 4 comments · Fixed by #2315
Closed

Rearchitect documentation generator from markdown #1429

Racer159 opened this issue Mar 10, 2023 · 4 comments · Fixed by #2315
Assignees
@Noxsios
Labels
needs-adr PR Label - Architectural Decision Records required to merge tech-debt 💳 Debt that the team has charged and needs to repay

Comments

@Racer159
Copy link
Contributor

Racer159 commented Mar 10, 2023 •
edited
Loading

Describe what should be investigated or refactored

We have had issues with Docusaurus and would like to explore other options for hosting a documentation site. This should explore:

  1. If we can modify Docusaurus to fit our needs better
  2. If another solution better meets our needs

This should not lose the following:

  1. Search - including good index and offline support
  2. Support for custom MDX syntax (notes and admonitions)
  3. Configurability/themability

This will also need an ADR comparing different options and explaining why we went a particular direction.

Links to any relevant code

https://github.com/defenseunicorns/zarf/tree/main/docs-website

Additional context

This comes out of us looking at our docs and thinking about how we could incorporate them into Zarf to bring it along to the airgap.
@Racer159 Racer159 added tech-debt 💳 Debt that the team has charged and needs to repay needs-adr PR Label - Architectural Decision Records required to merge labels Mar 10, 2023
@Racer159
Copy link
Contributor Author

relates to - #1278

@Racer159
Copy link
Contributor Author

also - defenseunicorns/UnicornUI#86

@abhiyant-10
Copy link
Contributor

abhiyant-10 commented Mar 11, 2023 •
edited
Loading

We can also add DocsGPT support by training the model for Zarf , it can give better understanding to the users and also handle most of the queries .
Comparing GitBook , Gatsby , Docsify and MkDocs to find out which of them meet our requirements.
Gatsby can be considered as an option as I have seen Open source orgs using it and does meet the requirements stated above but not sure it completely aligns with our motive

@Racer159
Copy link
Contributor Author

Summarizing this thread (https://kubernetes.slack.com/archives/C03BP9Z3CMA/p1678915928812279):

I think this is a good place to build off from for an ADR I know @mike-winberry is working this: defenseunicorns/UnicornUI#86 to see if docs can just be inside of Zarf and there are other options we should explore (including Kiwix which we experimented with a while back: https://github.com/defenseunicorns/zarf/tree/example/kiwix) in addition to the more traditional md to docs generators.

The biggest thing will be offline support most likely since our primary deploy persona (Ashton) is usually less tech savvy, and won't always have internet access.

@Racer159 Racer159 mentioned this issue Feb 20, 2024
Merged
5 tasks
@Noxsios Noxsios self-assigned this Mar 7, 2024
Noxsios added a commit that referenced this issue Apr 9, 2024
@Noxsios @Racer159 @lucasrod16
feat(docs): port docs to starlight (#2315)
5a7314e 
## Description

Port docs to Starlight, restructure to delineate differences between
reference material and guides. Greatly consolidates information in
miscellaneous `.md` files across the repo to live within
`site/src/content/docs`. Lays a pathway for future docs work, and
hopefully no more large docs PRs.

## Related Issue

Fixes #1429
Fixes #1460
Fixes #1532
Fixes #1134 

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [x] Other (security config, docs update, etc)

## Checklist before merging

- [x] Test, docs, adr added or updated as needed
- [x] [Contributor Guide
Steps](https://github.com/defenseunicorns/zarf/blob/main/CONTRIBUTING.md#developer-workflow)
followed

---------

Signed-off-by: razzle <harry@razzle.cloud>
Co-authored-by: Wayne Starr <Racer159@users.noreply.github.com>
Co-authored-by: Lucas Rodriguez <lucas.rodriguez9616@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@Noxsios Noxsios

Labels
needs-adr PR Label - Architectural Decision Records required to merge tech-debt 💳 Debt that the team has charged and needs to repay
Projects
No open projects
Zarf Project Board
Status: Closed
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

feat(docs): port docs to starlight defenseunicorns/zarf
3 participants
@Racer159 @Noxsios @abhiyant-10