Axelerant Engineering Handbook

This handbook for Axelerant Engineering is written using Hugo. If you want to just get to the content, go straight to the hosted site. If you want to edit the content, go to the content directory and edit the post you want. You can also open this repository in Gitpod.

Contributing

The easiest way to edit content is from within GitHub itself. Find the Markdown file you want to edit in Github and click on the Edit button (it's an icon shaped like a pencil). While this is very quick, you can only edit one file at a time.

If you want to edit multiple files or have a preview before you commit, then click the button below to start a new development environment on Gitpod. You need a Gitpod account and you will be able to edit all the files in an IDE similar to VS Code running in your browser. Click on the button below to get started.

Local development

If the above doesn't work for you or you'd rather you do this locally, you need Hugo. Follow the instructions in the documentation to install Hugo.

Clone this repository and run Hugo as a server inside the repository directory.

git clone git@github.com:axelerant/engg-handbook.git
hugo mod get -u
hugo server -D

The above command, if it works correctly, will give you a link to view the generated site (typically http://localhost:1313/). You can now edit your files and see the changes immediately reflected in the browser. Once you're done, commit and push. Once it is merged into the main branch, your changes will be live.

Linting docs

We use MarkdownLint to lint the markdown files. This runs as a test on GitHub actions every time you raise a pull request. You can also run this on your local environment either by using the VSCode extension or using the Node package included. In the case of the latter, you can use yarn commands to run the linters.

yarn
yarn lint:md

Fixing linting issues

If you are seeing linting errors, most of them can be fixed by running scripts as below. It's a good idea to run the lint commands again to check if some of the errors couldn't be fixed and will need to be fixed manually.

yarn lint-fix:md
yarn lint-fix:prettier