Authelia has great documentation however there are always things that can be added. This section describes the contribution process for the documentation even though it's incredibly easy.
The website is built on Hugo using the Doks theme. Hugo is a powerful website building tool which allows several simple workflows for developers as well as numerous handy features like Shortcodes which allow building reusable parameterized sections of content.
Making a Change
Anyone can simply edit the Markdown of the relevant document which shares a path with the website URL under the docs folder on GitHub. In most if not all pages there is a link included at the very bottom which links directly to the Markdown file responsible for the document.
It’s relatively easy to run the Authelia website locally to test out the changes you’ve made.
- git (though this can be skipped if you just download the repository)
- Node.js and npm (bundled with Node.js)
The following steps will allow you to run the website on the localhost and view it live in your browser:
- Run the following commands:
git clone https://github.com/authelia/authelia.git cd authelia/docs npm run install npm run start
- Visit http://localhost:1313/ in your browser.
- Modify pages to see the effects live in your browser.
Most documents come with a front matter that looks similar to this:
--- title: "A Page Title" description: "This is a description of the page." lead: "This is a page lead." date: 2022-03-19T04:53:05+00:00 draft: false menu: development: parent: "prologue" weight: 100 toc: true ---
The front matter controls several aspects about how the page is displayed and varying other aspects.
Open Graph Protocol
First of all it’s important to understand the Open Graph Protocol. This is a protocol developed by Meta / Facebook
which is utilized by most social media platforms to display a preview of a website. This is done by customizing special
<meta /> tags.
This section documents each of the fields that we commonly use.
String. Configures the
<title /> element, the first
<h1 /> element, and the Open Graph Protocol
String. Configures the and the Open Graph Protocol
String. Configures the first paragraph of a page which occurs directly after the title.
Boolean. Configures the visibility of a page. If it’s set to
true it is invisible.
Dictionary. Configures the menu linkage.
Integer. Configures the position in the menu and the order in which pagination occurs.
Boolean. Enables or disables the Table of Contents or
On This Page section.
Boolean. Enables or disables the Community page header. This value only has an effect in the Integration section at this stage.