-
Notifications
You must be signed in to change notification settings - Fork 173
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(docs): port docs to starlight (#2315)
## 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 <[email protected]> Co-authored-by: Wayne Starr <[email protected]> Co-authored-by: Lucas Rodriguez <[email protected]>
- Loading branch information
3 people
authored
Apr 9, 2024
1 parent
4b54a69
commit 5a7314e
Showing
355 changed files
with
14,833 additions
and
31,291 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| { | ||
| // Disable some built-in rules | ||
| "config": { | ||
| "first-line-heading": false, | ||
| "line-length": false, | ||
| "single-h1": true, | ||
| "hr-style": false, | ||
| "no-trailing-punctuation": false, | ||
| "code-block-style": false, | ||
| "no-inline-html": false | ||
| }, | ||
| // Define glob expressions to use (only valid at root) | ||
| "globs": [ | ||
| "**/*.mdx", | ||
| "../**/*.md" | ||
| ], | ||
| "ignores": [ | ||
| "**/node_modules/**", | ||
| "src/content/docs/commands/*.md", | ||
| "site/src/content/docs/commands/*.md" | ||
| ] | ||
| } |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,76 @@ | ||
| # 24. Migrate documentation to Starlight | ||
|
|
||
| Date: 2024-03-30 | ||
|
|
||
| ## Status | ||
|
|
||
| Accepted | ||
|
|
||
| ## Context | ||
|
|
||
| The current documentation site is built with Docusaurus 2. While Docusaurus has served us well, it has some limitations, primarily around performance and dependency management. | ||
|
|
||
| ### Proposed Solutions | ||
|
|
||
| 1. [**Starlight**](https://starlight.astro.build/) is a new documentation site generator that is built with performance in mind. It is a lightweight, fast, and flexible static site generator powered by [Astro](https://astro.build) that is designed to be easy to use and extend. | ||
|
|
||
| - **Pros**: | ||
| - Fast performance. | ||
| - Easy to extend with custom components in any framework. | ||
| - Built-in support for MDX. | ||
| - Simplified build process. | ||
| - Better control over dependencies. | ||
| - Client-side static site search built-in. | ||
| - Excellent default theme. | ||
| - **Cons**: | ||
| - Newer project with a smaller ecosystem compared to others. | ||
| - Much fewer plugins and themes available compared to other static site generators. | ||
| - Only absolute URLs are supported for cross-site links (relative image URLs are supported). | ||
|
|
||
| 2. [**Hugo**](https://gohugo.io/): is another popular static site generator that is known for its speed and flexibility. It is written in Go and has a large ecosystem of themes and plugins. | ||
|
|
||
| - **Pros**: | ||
| - Fast performance. | ||
| - Large ecosystem of themes and plugins. | ||
| - By default no JavaScript is required. | ||
| - **Cons**: | ||
| - Fewer built-in features compared to others, much more of a DIY approach. | ||
| - Steeper learning curve compared to others. | ||
| - More complex build process. | ||
| - Not as easy to extend with custom components. | ||
| - Theme management is abysmal w/ a combination of Go modules, Git submodules, and NPM packages. | ||
| - Zero documentation themes the team liked, leading to the quandry of whether to build, and having to maintain, a custom theme. | ||
|
|
||
| 3. [**Material for MkDocs**](https://squidfunk.github.io/mkdocs-material/): is a popular static site generator geared towards project documentation. The Material for MkDocs theme provides a clean and responsive design. | ||
|
|
||
| - **Pros**: | ||
| - _Amazing_ default theme and developer experience for writing docs. | ||
| - Easy to use and extend. | ||
| - Large ecosystem of plugins. | ||
| - **Cons**: | ||
| - Not as flexible as Hugo or Starlight. | ||
| - Making custom components can be more challenging. | ||
| - Brings in Python dependencies (not a really huge detractor, but the team would like to reduce dependencies on different languages where possible). | ||
|
|
||
| ## Decision | ||
|
|
||
| To simplify the development process and improve the performance of the documentation site, we have decided to migrate to Starlight. This is based upon a number of factors: | ||
|
|
||
| - Small dependency footprint. | ||
| - Fast performance. | ||
| - Easy to extend with custom components. | ||
| - Built-in support for MDX. | ||
| - The majority of the features we need are built-in and require minimal configuration. | ||
| - Client-side static site search | ||
| - Sane spacing and typography | ||
| - Dark mode + light mode | ||
| - Syntax highlighting | ||
| - Responsive design + mobile-friendly | ||
| - Tabs + Admonitions | ||
|
|
||
| ## Consequences | ||
|
|
||
| - During the transition, we will need to update the existing documentation content to work with the new site generator. Additionally, the site archictecture will be re-evaluated and optimized. This _will_ result in many links to current content breaking. | ||
| - Every documentation generator has its quirks and limitations, so we will need to adapt to the new workflow and learn how to best utilize the features of Starlight. | ||
| - The migration will take time and effort, but the benefits of improved performance and flexibility will be worth it in the long run. | ||
| - The team will need to learn how to use Astro and Starlight, which may require some training and experimentation. |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.