https://regolith-desktop.com website
This is theThis site uses the Hugo static site generator and the Book theme.
Local Development
Please ensure you have the following installed:
- Hugo extended >= 0.80.0 (otherwise PostCSS won't work)
- npm
- git
Checkout and View Local
Clone this repo, and the Book theme as a submodule:
$ git clone --recurse-submodules --depth 1 git@github.com:regolith-linux/regolith-desktop-website.git regolith-desktop-website
$ cd regolith-desktop-website
Install dependencies and launch Hugo server:
$ npm install
$ hugo server
...or, with Docker:
docker-compose up
NOTE: If you encounter an error like failed to extract shortcode: template for shortcode "columns" not found
, you forgot the submodule for the Book theme.
git submodule update --init --depth=1
Make changes
Edit content as needed. If hugo server
is running then updates are automatically reloaded after committing changes to disk.
Update website on GitHub Pages
GitHub Actions on the repository is configured to deploy any and all changes to the v2
branch automatically, no further action needed. The CNAME
(https://www.regolith-linux.org) is configured automatically, no need to add it.
If you believe that your changes ought to be reviewed by a second party, just open a pull request and have somebody else jump in and cross-check your edits.
Shortcodes
Additional shortcodes are:
keys
: To insert a recognizable sequence of keypresses, e.g.{{< keys "super,shift,q" >}}
. The block also accepts an optional delimiter, should you need,
as a keypress, e.g.{{< keys "super|," "|" >}}
img
: To insert an image, including automated, cross-device sizing, a lightbox and an alt text, e.g.{{< img "images/my-image.jpg" "Some alt text" >}}
supported_version
: To insert the Ubuntu versions, delimited by commas, which are currently supported by Regolith Linux, e.g.{{< supported_versions >}}
(they are taken from theconfig.toml
params
section). You can either choose to display the version numbers or the version names, with numbers being the default. To display the names use{{< supported_version type="names" >}}
Conventions
Use Markdown wherever possible
Although Hugo accepts common HTML elements pretty much anywhere the expressed goal is to rely on Markdown and its syntax for pretty much anything within the confines of the content
directory itself. If you need to style something differently, try using a shortcode first, before actually styling the page in "pure" HTML. Some pages are violating this concern, mostly because the underlying theme does as well, but for the sake of making it easier on folks to edit and especially translate the content as well as keeping a consistent style across languages they should be free of HTML.
prettier
for formatting files (especially Markdown)
Use prettier
is a versatile formatter for JavaScript/TypeScript and everything related to HTML as well as JSON/YAML and TOML. Please use it to format all the content in the repository that prettier
is capable of processing. Manual formatting will show up as an error in the future and PRs changing formatting that's different from prettier
output will not be accepted.
console
for highlighting shell session code
Use Using bash
obscures the flow of information and things you type into a session isn't really shell code all the time but rather a random set of commands. There's an open feature request with the highlighting engine ("Chroma") Hugo is using to accept console
as a lexer. Once that's accomplished all the relevant highlighting parts will look different. For now, they'll just receive the default styling.
Xresources
(with backticks)
Call it No Xresource
or Xresource. Use the plural (because that's what we read and what the definition of the mechanism is) and surround the word itself with backticks to make it stand out a little.
assets/images
and use the img
shortcode
Put images into We don't want duplicate content anywhere, especially not images that are the same for every single translation. Therefor we put images into the assets/images
folder and use the img
shortcode to refer to them. You'll get a lightbox and automated, screen-aware (i.e. "mobile friendly") sizing on top. The img
shortcode has the following syntax:
{{< img "<path-to-image-in-asset-folder>" "alt-text-for-image" >}}
Example:
{{< img "images/my-image.jpg" "Some image" >}}
ref
or relref
for linking between content
Use Content changes, page names change. Using a hardcoded path in Markdown links will break sooner or later. Hugo has two built-in functions, ref
(preferred) or relref
, to make sure links are viable and linking to the right content. Use them whenever you're linking to "internal" content.
Note: Hugo will fail to render the page if a link is "dead" and you will have to fix it before you can continue. We consider this a feature!
Use the Markdown footnote syntax to render footnotes
Hugo allows for specifying footnotes in the regular Markdown syntax, e.g. [^1]
for the note in the text and [^1]: Some text
(mind the colon) wherever you want to place the footnote text. It has the added advantage that the footnote also links back to the text.