Repository files navigation

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.

1. Install Hugo on your system.Ensure you get theextended version.
2. Open a terminal in the directory in which you cloned this repo and type the commandhugo server -b localhost.
3. Point your browser tolocalhost:1313 and the documentation should appear.

The main content for the site is stored in, unsurprisingly, thecontent 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 theBasic Topics section is stored incontent/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, theReference: 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 Hugoref orrelref 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 thestatic/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 calledmy-image.png in the docs images folder, I could then use this markdown to display it:

![Alt Image Text](img/docs/my-image.png)

Alerts can be used to help grab the reader's attention for important things such as warnings. An alert can be created using thealert 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>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 inthemes/aurora.

The main structure of the page is stored inthemes/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 inthemes/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 thethemes/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 inthemes/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 thethemes/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.