Website with Hugo #279
Website with Hugo #279
Conversation
|
/cc @annafil |
snazy
force-pushed
the
website-hugo
branch
29 times, most recently
from
de11443 to
cf36451
Compare
An approach for the website using Hugo, built to support docs for Polaris releases.
The current state is rather a demo for the versioned docs than something that can be published.
Follow the _Quickstart_ to start/stop Hugo in a Docker container or run it locally, as you prefer.
** Versioned docs demo **
1. Start Hugo - the `Docs & Releases` menu at the top has only the `In Development` menu item.
2. Stop Hugo
3. Run the `site/bin/checkout-releases.sh` script (it requires the `versioned-docs` branch from my fork)
4. Start Hugo - the `Docs & Releases` menu has a couple more menu items.
The "released versions" are categorized into "active" and "EOL" versions - only the "actively maintained" versions appear in the menu in the navbar.
** Quickstart **
Just run the following command to let Hugo serve files from the Polaris `site/`.
```bash
site/bin/run-hugo-in-docker.sh
```
Then point your browser to http://localhost:1313/
To stop the Hugo run
```bash
site/bin/stop-hugo-in-docker.sh
```
See `README.md` in the `site/` directory for more options
** Versioned docs **
The idea here is that docs of releases live in either a separate branch or a separate Git repo.
The `/releases` folder would _not_ be in the main Polaris repository (at least not in any code branch). It would be
mounted either via `git worktree` or `git clone`. Building and testing the site locally works without the `/releases`
folder. For developers, it is probably much easier to have a separate branch in the main Polaris GitHub repository
and leverage Git worktrees.
Docs for the current code branch (e.g. `main` branch) are maintained in the `/in-dev/unreleased` folder. While we
could maintain the docs right in the `/in-dev` folder, having the in-dev docs in `/in-dev/unreleased` provides the
ability to use relative links that still work when the docs are in an `/releases/x.y.z` folder (think: links like
`../../guides/foo-bar.md`).
Within a release's versioned docs folder, the release version number can be included in the markdown using the
custom Hugo shortcode `{{< releaseVersion >}}`.
* Use new logo * remove current `docs/` (after migrating changes in there) * remove demo content * update community pages (remove demo content) * hide "blog" and "guides" (currently empty) * remove (hopefully) unused files in `spec/` * added Hugo shortcode to include the "in-dev"/"release-version" openapi specs, depending on the source page
|
I've updated & polished the PR and it is now (nearly) ready. The missing piece is currently a secret for the polaris-site repo to deploy to the |
snazy
requested review from
jbonofre,
ashvina,
RussellSpitzer,
vvcephei,
takidau,
jackye1995,
flyrain,
eric-maynard,
collado-mike and
ebyhr
as code owners
There was a problem hiding this comment.
Thanks a lot, @snazy, for your work on this! The new site looks fantastic, and I'm really excited about it.
Just a minor observation: there are currently three directories under static—images, img, and favicons—all holding images. It seems like having three separate directories might not be necessary. This isn't a blocker, we can always improve it over time.
|
|
||
| menu: | ||
| main: | ||
| - name: "Docs & Releases" |
There was a problem hiding this comment.
Minor: split them into two top level menu?
There was a problem hiding this comment.
The idea here is to have one set of versioned docs that contain both the docs and download links / distribution information.
|
|
||
| openapi: 3.0.3 | ||
| info: | ||
| title: Polaris Management Service |
There was a problem hiding this comment.
Do we need this file? Can we use the one in directory spec?
There was a problem hiding this comment.
Ah - yea. Those can go away.
|
Thanks for the review! |
|
Nice, the GH workflow worked out of the box and populated the new |
An approach for the website using Hugo, built to support docs for Polaris releases.
The current state is rather a demo for the versioned docs than something that can be published.
Follow the Quickstart to start/stop Hugo in a Docker container or run it locally, as you prefer.
** Versioned docs demo **
Docs & Releasesmenu at the top has only theIn Developmentmenu item.site/bin/checkout-releases.shscript (it requires theversioned-docsbranch from my fork)Docs & Releasesmenu has a couple more menu items.The "released versions" are categorized into "active" and "EOL" versions - only the "actively maintained" versions appear in the menu in the navbar.
** Quickstart **
Just run the following command to let Hugo serve files from the Polaris
site/.Then point your browser to http://localhost:1313/
To stop the Hugo run
See
README.mdin thesite/directory for more options** Versioned docs **
The idea here is that docs of releases live in either a separate branch or a separate Git repo.
The
/releasesfolder would not be in the main Polaris repository (at least not in any code branch). It would be mounted either viagit worktreeorgit clone. Building and testing the site locally works without the/releasesfolder. For developers, it is probably much easier to have a separate branch in the main Polaris GitHub repository and leverage Git worktrees.Docs for the current code branch (e.g.
mainbranch) are maintained in the/in-dev/unreleasedfolder. While we could maintain the docs right in the/in-devfolder, having the in-dev docs in/in-dev/unreleasedprovides the ability to use relative links that still work when the docs are in an/releases/x.y.zfolder (think: links like../../guides/foo-bar.md).Within a release's versioned docs folder, the release version number can be included in the markdown using the custom Hugo shortcode
{{< releaseVersion >}}.