The build process is fairly automated and doesn't require much thought. But it is interesting to understand how one actually would improve the website.
Writing documentation to the website in not more complex than it normally is. Making
changes to the Markdown files in
./docs is everything one need to do.
If a new file is created and it should be in the website's sidebar menu, then remember
Here are some guidelines that are helpful when writing good documentation:
async-awsto refer to the project.
- Don't use "we" at any cost.
- Try not to write "you".
- Define all variables to make examples executable.
- Use meaningful names of variables and values. Avoid "foobar" and other dummy values.
- Write examples with use
usestatements and don't use
- Use input objects over arrays.
- Use short variable names for clients. Ie
Improving the website's appearance¶
To update the websites HTML or style one need to use Couscous. Its basic operations are found in their Getting started guide. You do also need NPM installed to build the assets.
There is a Makefile script to run
npm install and
encore prod. It will be executed
make website-assets. That script will automatically run before Couscous is
generating the HTML.
What you basically need to do is to open two terminals. In one you run
And to make sure the assets are updating when you making a change to the asset source:
cd website ./node_modules/.bin/encore dev --watch
Now you are good to go.
The process of building the website¶
So here is an overview how the automated build process works every time there is a push to master:
1. Generate the HTML¶
The first step is to use Couscous to convert all Markdown files
./docs to HTML files. Couscous then looks at the Twig template in
to get the basic HTML layout. All markdown files will use the
unless other is specified at the metadata section at the top of the markdown file.
The sidebar menu structure is defined in
All frontend assets are built using Webpack Encore. The source files lives in
2. Process HTML files¶
After the HTML files are generated, Couscous will execute
That will look at the generated HTML and make some changes to it. As example it will
style all code examples with