Guides#

These are community-written guides for blendOS.

Disclaimer

This section is for user-specific, app-specific or miscellaneous guides. Anything specific to a utility, official guide, or config should be contributed to their respective pages.

These guides are validated by the blendOS team, but they do not reflect the views of the team or the project. If you have issues with a guide, contact its creator.

Recent Guides#

Using Podman by @Ast3risk-ops

How do I write a guide?#

It's pretty simple (and requires Git and Python (already installed if you're on Linux) to be installed, we'll walk you through it).

You'll also wanna see our contributing information for how to write with Material for MkDocs and our style rules.

Installing Git

Git is a CLI version control tool (from your terminal)

On Windows you can use Git Bash (part of Git for Windows)

On macOS you can install the XCode command line tools (type git into your terminal, you'll be prompted)

On Linux, use your package manager (usually preinstalled)

If this sounds too hard, you can use one of many Git GUI programs (not Github Desktop, that won't work with Gitlab).

If you have Git installed, most editors will also have a Git client (Source Control in VSCode) that will handle everything for you.

Setting up your local Git profile

You'll want to do this for your profile to show up properly in commit history.

Do the following:

git config --global user.name "Your Username"

git config --global user.email "Your Gitlab commit email"

If you already have set this up for Github and use different values, cd to your cloned project and use git config (without --global)

If you need a crash course on Git, there's plenty available online. Here's the basic writing steps:

Sign up to our Gitlab instance and verify your account (more info about that during signup, you just have to contact an admin)
Fork the docs repo (click Fork at the top, make sure to choose All branches)
Clone your fork (Click clone, then copy the Clone with HTTPS url and clone it with your Git program):
```
git clone <YOUR_CLONE_URL>
```
cd to your cloned folder and change to the dev branch:
```
git checkout dev
```
Copy docs/guides/example.md to a new file in the same folder and edit it (don't edit the template directly)

Add your guide to mkdocs.yml:

mkdocs.yml

nav:
  # other navigation items
  - Guides:
    - Guides: guides/README.md
    - Your Guide Title: guides/your-guide.md

Edit docs/guides/README.md to add your guide to the recent guides following the example in the comment
To preview your changes, see the guide in the contributing section
Create an access token (tick the write_repository and read_repository boxes) to authenticate your changes.
Commit your changes (you'll be asked for a username and password, put your username for the username, then for the password, put your access token):
```
git add * && git commit -m "your commit message" && git push origin dev
```
Make a merge request from your fork to the main repo (check to make sure the merge destination is the dev branch)