You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polaris.apache.org by "snazy (via GitHub)" <gi...@apache.org> on 2024/09/11 12:35:53 UTC

[PR] Website with Hugo (WIP!) [polaris]

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: commits-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Website with Hugo (WIP!) [polaris]

Posted by "snazy (via GitHub)" <gi...@apache.org>.
snazy commented on PR #279:
URL: https://github.com/apache/polaris/pull/279#issuecomment-2346140234

   Okay - this one should work now work in all environments (podman + Docker) and relevant OS (Linux + macOS).
   
   Manually verified on:
   * Linux (Ubuntu 24.04) with podman + podman-compose
   * Linux (Ubuntu 24.04) with Docker + [docker-compose](https://github.com/docker/compose) (AL-2)
   * macOS with podman Desktop
   * Github workflow (included in this PR) with Docker + [docker-compose](https://github.com/docker/compose) (AL-2)
   
   It's only necessary to run `site/bin/run-hugo-in-docker.sh` to start Hugo for local site development.
   `site/bin/create-static-site.sh` creates the static site for the project site base URL,
   `site/bin/create-static-site.sh --local` creates the static site for local inspection and a http server for it.
   
   There should be no need to call `site/bin/stop-hugo-in-docker.sh` (the above scripts have a "clean up trap"), but I left it there just in case.


-- 
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: commits-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Website with Hugo (WIP!) [polaris]

Posted by "snazy (via GitHub)" <gi...@apache.org>.
snazy commented on PR #279:
URL: https://github.com/apache/polaris/pull/279#issuecomment-2343551466

   /cc @annafil 


-- 
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: commits-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org