This is the Hugo documentation for the Aurora RGB lighting software.
If you only wish to view the documentation, you're in the wrong place! Go here instead!
Though you do not require a local test environment to make changes since the site is built by GitHub Actions, you may wish to preview changes locally.
- Install Hugo on your system. Ensure you get the extended version.
- Open a terminal in the directory in which you cloned this repo and type the command
hugo server -b localhost. - Point your browser to
localhost:1313and the documentation should appear.
The main content for the site is stored in, unsurprisingly, the content folder. In here are the folders for each section, with individual content pages in each section folder.
Each section is displayed separately in the left navigation pane, with each page in that section appearing below the section's heading. The metadata for the section is stored inside the _index.md file inside the section folder (e.g. the frontmatter for the Basic Topics section is stored in content/basic-topics/_index.md). This metadata contains a display name for the section as well as a numeric order for where the section will appear in the navigation, with lower numbers as the top.
New sections can be made simply by adding a new folder and providing it with an _index.md file and subpages.
Each page is an md file in the relevant section's folder. The pages also have similar frontmatter, though this is stored in the markdown at the top of the file. This, again, contains a display name and an optional order property (for multiple items with the same order, the items are sorted by title; for example, the Reference: Layers section does not use order since we want them to all appear alphabetically). In addition to this, it also stores a list of authors for the page, with the author's name being their github username. Their github avatar will appear at the bottom of the authored page. Anything after the frontmatter is treated as the main content of the page.
You should view some of the existing pages for an example on how to structure a page.
References to other pages should be done using the Hugo ref or relref shortcodes. For example, to link to the installation page, the markdown code would be:
[Link text]({{% ref "basic-topics/installation" %}})To link to a page in the same section, you can use relref:
[Link text]({{% relref "page-in-same-section" %}})Images should be placed in the static/img/docs folder. Then they can be simply used using a normal markdown image tag with static as the root directory. For example, if I had a file called my-image.png in the docs images folder, I could then use this markdown to display it:
Alerts can be used to help grab the reader's attention for important things such as warnings. An alert can be created using the alert shortcode.
{{% alert "My alert message goes here!" "warning" %}}The second parameter ("warning" in the example) is the type of alert. This can be one of the following: "danger", "warning", "info", "success".
Note that if you are adding a link or html to the alert, the shortcode cannot be used and one must instead provide the html. At time of writing this is <span class="alert danger">Alert text here</span>, though the shortcode is preferred when possible should the markup change in future.
The site's structure and styling is stored as part of a custom Hugo 'theme'. This is stored in themes/aurora.
The main structure of the page is stored in themes/aurora/layouts/_default/baseof.html. This is used as the base template for all pages. The partials that are referenced in this html template are stored in themes/aurora/layouts/partials. This allows us to breakup the template into smaller and more-easily managed files, potentially reusing them in future if the need arises.
The CSS for the site is generated from SCSS files which are stored in the themes/aurora/assets/scss directory. Any changes made to the style should be done in here, not the autogenerated CSS file.
The JavaScript for the site is stored in themes/aurora/assets/js. As part of the build process, this JavaScript is minified and fingerprinted. If you wish to add a new JS file, add it to the js folder and then add alter the themes/aurora/layouts/partials/scripts.html partial file with the new file. You will need to add a new resource variable and then pass that variable into the scripts array.