Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/axelerant/engg-handbook
Axelerant Engineering Handbook
https://github.com/axelerant/engg-handbook
handbook hugo-site
Last synced: 3 days ago
JSON representation
Axelerant Engineering Handbook
- Host: GitHub
- URL: https://github.com/axelerant/engg-handbook
- Owner: axelerant
- Created: 2022-08-18T20:11:32.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-12-31T21:36:54.000Z (8 days ago)
- Last Synced: 2024-12-31T22:24:09.153Z (8 days ago)
- Topics: handbook, hugo-site
- Language: HTML
- Homepage: https://engg-handbook.axelerant.com/
- Size: 1.45 MB
- Stars: 3
- Watchers: 8
- Forks: 11
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Axelerant Engineering Handbook
[](https://app.netlify.com/sites/axelerant-engg-handbook/deploys)
This handbook for Axelerant Engineering is written using [Hugo](https://gohugo.io/getting-started/quick-start/). If you want to just get to the content, go straight to the [hosted site](https://engg-handbook.axelerant.com/). If you want to edit the content, go to the [content](content/) directory and edit the post you want. You can also [open this repository in Gitpod](https://gitpod.io/#https://github.com/axelerant/engg-handbook).
## 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.
[](https://gitpod.io/#https://github.com/axelerant/engg-handbook)
### 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](https://gohugo.io/getting-started/installing/) to install Hugo.
Clone this repository and run [Hugo as a server](https://gohugo.io/getting-started/quick-start/#step-5-start-the-hugo-server) inside the repository directory.
```bash
git clone [email protected]: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/](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](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint) or using the [Node package](https://github.com/DavidAnson/markdownlint) included. In the case of the latter, you can use `yarn` commands to run the linters.
```bash
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.
```bash
yarn lint-fix:md
yarn lint-fix:prettier
```