snazy opened a new pull request, #279: URL: https://github.com/apache/polaris/pull/279
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 >}}`. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
