Contributing#

Read the Git structure page, then go see an area of contribution below:

Git Structure#

Our repositories are split across multiple places, this is the average contribution path:

flowchart TD
    A[New User] -->|Wants to contribute| B(Needs source code)
    B -->|Google results bring up Github| C{Where?}
    C -->|Newer v4-related repos| D(Gitlab instance)
    C-- Old + 'meant to be forked' repos -->E(Our Github organization)
    D --> F[User forks]
    E --> G[User forks]

Most users will never find the Gitlab and will see old decrepit repos alongside newer ones on our Github organization. Please remember all new repos are on our Gitlab instance, except for "meant to be forked" repos.

You should already know how to use both services depending on what you're contributing to. For things like the tracks repo, view the Github start guide. For all v4-related repos on our Gitlab, see Gitlab's start guide.

Mirroring#

If you'd like to mirror our package repo and/or ISOs, here's the basics for it.

Current (ish) stats#

Size: 3 GB (repo and current testing ISO)
Number of files: 36
Mirrors: 7 (excluding cloud storage services)
Coverage: NA, EU, AU/NZ, KP
Rsync: (available from other mirrors)

A mirror list is available on the download page.

Procedure#

If you'd like to mirror, great! Here's the steps:

Note down your mirror's bandwidth (in Gbps), country, name, and what you'll be serving (ISO-only, repo-only or both)

Clone the master package repo mirror via wget and grab the latest ISO:

ISO mirroring

You can use the following script:

#!/bin/bash
ISO_URL="https://git.blendos.co/api/v4/projects/32/jobs/artifacts/main/raw/blendOS.iso?job=build-job"
LOCAL_ISO_PATH="/var/www/mirrors/blend/isos/v4/blendOS.iso"
ISO_VERSION_URL="https://git.blendos.co/api/v4/projects/32/jobs/artifacts/main/raw/version?job=build-job"
LOCAL_VERSION_FILE="/var/www/mirrors/blend/v4/testing/version"

download_iso() {
    rm -rf $LOCAL_ISO_PATH
    wget -O "$LOCAL_ISO_PATH" "$ISO_URL"
    wget -O "$LOCAL_VERSION_FILE" "$ISO_VERSION_URL"
}

get_remote_version() {
    wget -O - "$ISO_VERSION_URL"
}

REMOTE_VERSION=$(get_remote_version)
LOCAL_VERSION=$(cat "$LOCAL_VERSION_FILE")

if [ "$REMOTE_VERSION" != "$LOCAL_VERSION" ]; then
    echo "New ISO version detected. Downloading..."
    download_iso
    echo "$REMOTE_VERSION" > "$LOCAL_VERSION_FILE"
else
    echo "ISO is up-to-date."
fi

Replace LOCAL_ISO_PATH and LOCAL_VERSION_FILE with the path to your webserver followed by blendOS.iso and version respectively. Keep the file names as-is.

Set this up to a systemd timer unit or cronjob, and it will keep everything up-to-date.

wget mirroring for the package repo

Otus has provided a cronjob for this:

0 * * * * wget --mirror --no-parent --no-host-directories -P $WEB_FOLDER https://pkg-repo.blendos.co/ && find $WEB_FOLDER -type f -name 'index.html*' -delete

Where $WEB_FOLDER is your web data folder.

This tells wget to download everything without any parent or domain folders, then we use find to remove all the index.html files.

I wish we had rsync too, but here we are.

If mirroring the ISO, add a CORS header to allow us to fetch your version file:

Examples taken from the MDN web docs.

Access-Control-Allow-Origin: https://blendos.co

Apache

Header set Access-Control-Allow-Origin 'https://blendos.co'

Nginx

add_header 'Access-Control-Allow-Origin' 'https://blendos.co' always;

The caddy.cors plugin is not available for Caddy v2.

Caddy (v2)

header Access-Control-Allow-Origin "https://blendos.co"

Contact Asterisk via one of our chatrooms (in the footer of this page) to get your mirror listed

Notes#

You will be asked if you'd like to be used as a webseed for the FOSS Torrents torrent. This is totally up to you.

You will be added to our status page and pinged every 60 seconds. Please give us details if we need to ping something specific or if you want notifications.

If you have any questions, just contact us.

Docs#

Gitlab - CC BY-SA 4.0 - Material for MkDocs

Rules#

If you would like to add to our docs (please do), you should follow these simple rules.

Keep it local. If you use any external assets, download them. Only do not download something if it is dynamic (like a status badge) or there is no other way (like emoji). Static badges, script links pointing to fixed versions, fonts, images, files, download them all. Save them in the right category in the docs/assets folder. This is to minimize external requests.
Link code properly. Any code snippets you add should be snippet links to the original file if applicable. You can pull specific lines or even create sections to do this. Only do not do this if it would be way too cumbersome.

External links should open in a new tab with no referrer. (unless you have a specific reason not to) Make links like this:

https://google.com{ target="_blank" relk="noopener noreferrer" }
[link text](https://google.com){ target="_blank" rel="noopener noreferrer" }

Use frontmatter. Set an icon and description for every page (examples can be seen in the source of any page). Include all pages in the nav: component of mkdocs.yml unless there is a reason not to.
Be descriptive. When writing config and CLI references especially, try to show, not tell. A full description of this approach can be seen in the Diátaxis framework: diataxis.fr/reference-explanation/
Follow the format. We have established formats for directory pages and references. Follow them. Headers have icons. References begin with a reference card. Config references need to use code annotations. CLI references should be easy-to-read lists (showing the code like in the bpkg reference is optional). Directory pages should use cards to show what users can click on.
Keep it navigateable. Mobile users should not have to open the hamburger menu to get anywhere on the site from the root (they can still use it to go back or to skip directory pages).
Be semi-casual. For guides, you may find it better to be less distant from the reader. However, you need to also offer a reliable explanation of steps. You can decide what that looks like. References however, should always be distant (rule 5).
Use the features given to you. Be expressive! You are writing with one of the most powerful documentation frameworks out there, so use it! Don't be afraid to try something new in your writing, style or layout.
Always have a Javascript-free option. You can use the noJs system to pull this off.
Always give your headers icons. This helps them look nice, and will be even nicer once the typeset plugin hits the community edition.
Header titles must match page titles. Each page will have one level 1 header. Make your header like this: # :<icon-you-used>: <nav-title>
Merge to dev. This way you can preview everything before pushing it out.

Local Development#

Local development is quite easy. You'll only need:

Python ≥ 3.9
pip package manager (included with Python on Windows)

Using pipenv if pip cannot be used directly

Install pipenv from pypi or your package manager.

Then do the following in the project folder:

pipenv install

Then, as pipenv says, you can use pipenv shell and pipenv run:

pipenv run mkdocs serve

Simply cd in and run (this command only has to be run once):

pip install -r requirements.txt

From there, start the dev server:

mkdocs serve

The server will reload after every save.

If you want to build the website into static HTML, run this command (this isn't required for contribution, the CI/CD server does it automatically):

mkdocs build

Writing#

To learn how to write with Material for MkDocs, consult their reference and extension list to see its special components.

Looking for examples?

Just click the on any page to view its source code!

Images and internal links are created relative to the file you're currently editing. Links should link to the markdown file itself, not a path. (e.x. reference/README.md ../assets/img/file.png)

An overview of a few cool features you can use ( denotes a custom feature):

Admonitions (`admonition`)#

!!! <type> "<title>"
    text

??? warning "collapsable"
    text

!!! note inline end <!-- or inline --> "Inline"
    text

??? abstract follow "󰩳 This one's header will follow you down the page!"
    looooong text



    a

    a

    a

    a

    a

    a

    a

    a

collapsable

text

Inline

text

This one's header will follow you down the page!

looooong text

a

In addition to the regular admonition types, we have also added a code admonition for making collapsable codeblocks:

??? code "󰩳 file_name.ext"     <-- 󰩳 This has follow on by default
    ```
    code here, no space between admonition and code
    ```

file_name.ext

code here

As well as a collapse admonition:

??? collapse "󰩳 X lines collapsed"    <-- 󰩳 This also has follow on by default
    1

    2

    3

X lines collapsed

1

2

3

And video:

??? video "󰩳 Video Guide"
    <center>
    <video src="/assets/vid/example.webm" controls></video>
    <p>You should set a width and height if the video is too big, 
    and muted if it has no sound. 
    This p section can be omitted if no caption is required.<p>
    </center>

Video Guide

You should set a width and height if the video is too big, and muted if it has no sound. This p section can be omitted if no caption is required.

Emojis/Icons (`emoji`)#

Call them via their shortcode:

:lobster:

Call icons the same way:

:material-home:

One thing that is a bit different on these docs vs. other sites is you can use icons in codeblocks. Our codeblocks use a Nerd Font, which allows you to use icons within your code.

󰩳 I'm an icon!

Visit the cheatsheet: www.nerdfonts.com/cheat-sheet

Find the icon you want and hover over it. In the copy section, hit Icon. Your editor will probably not be able to render the icon as it is not using a Nerd Font. Rest assured, it will render in your preview.

CSS in Markdown (`attr_list` & `pm_attr_list`)#

[link](url){ option=value .class #id }

Markdown in HTML (`md_in_html`)#

<div markdown>
  **Markdown works** __just fine!__{ .someclass }
</div>

Markdown works just fine!

Code Snippets (`snippets`)#

File paths are relative to the repo root.

--8<-- "link_or_file.ext"

  ```
  --8<-- "link_or_file.ext"
  ```

We use this to make reusable Markdown snippets, and pull the latest version of a code file.

Keybinds (`keys`)#

++ctrl+alt+delete++

Ctrl+Alt+Del

Inline Syntax Highlighting (`inlinehilite`)#

`#!lang code`

`#!python print("Hello World!")`

print("Hello World!")

Automatic Links (`magiclink`)#

https://google.com

google.com

It also works for Github/Gitlab/Bitbucket links too!

Legend: ! = PR # = Issue ? = discussion ... = Compare

MagicLink supports shorthand references for GitHub, GitLab, and Bitbucket issues (#1), pull/merge requests (!100), GitHub Discussion 
(https://github.com/facelessuser/pymdown-extensions/discussions/1173), commits (23bb7083b4699703241d7552ff666cf8cef61337), and compares 
(23bb7083b4699703241d7552ff666cf8cef61337...0abca9679ec09ca289c345cc8843497fc0f8be9b). You can also reference repositories (https://
github.com/facelessuser/pymdown-extensions) and users (@facelessuser). Mentions also works for social media (only Twitter is supported 
at this time).

MagicLink supports shorthand references for GitHub, GitLab, and Bitbucket issues (#1), pull/merge requests (!100), GitHub Discussion (facelessuser/pymdown-extensions?1173), commits (23bb708), and compares (23bb708...0abca96). You can also reference repositories (facelessuser/pymdown-extensions) and users (@facelessuser). Mentions also works for social media (only Twitter is supported at this time).

If you do not specify a repo, the default repo will be used (here, it's blend-os/blendos (Github)).

You can also specify links to our git server:

Gitlab subgroups do not work.

󰩳 @blendgit:asterisk
󰩳 @blendgit:blendos/docs

@asterisk

blendos/docs

There's a lot more!

See the full reference and extension list for more cool features.

Javascript#

If you add custom HTML elements with Javascript, please use the noJs system to provide a Javascript-free option.

Add this section to the page:

<script>
    var styleSheet = document.createElement("style")
    styleSheet.innerText = '.noJs { display: revert !important }'
    document.head.appendChild(styleSheet)
</script>

This script will show noJs elements (which are hidden by default) and will not run if Javascript is disabled.

Next, give the trigger of the Javascript (i.e. a button) and/or the <div>/<span> where the Javascript inserts content the noJs class.

Now, if you have a Javascript-free replacement (a warning saying you need Javascript or a replacement button), put it in a <noscript> tag.

No external libraries should be used unless they are either essential (can't be done without JS and this library) or the rest of the docs could benefit from them. If either of these things are the case, rule 1 still applies, do not use a CDN.

Example:

awesome-page.md

<script>
    console.log("Hello!")
    document.getElementById('someDiv').innerHTML = "html goes here"
</script>

<span id="someDiv" class="noJs"></span>

[Button](javascript:history.forward){ .noJs .md-button }

<noscript>You need Javascript for this.</noscript>

**content**

<script>
    var styleSheet = document.createElement("style")
    styleSheet.innerText = '.noJs { display: revert !important }'
    document.head.appendChild(styleSheet)
</script>

Macros#

We have set up mkdocs-macros to turn MkDocs into more of a wiki engine.

We have created the following macros:

Package links (v4 containers only)

{{ aur("aur-package") }}

vesktop-bin^AUR

{{ archpkg("some-package") }}

linux-zen

{{ ubpkg("some-ubuntu-thing") }}

software-properties-common

{{ debpkg("some-debian-thing") }}

apt-transport-https

{{ fedorapkg("some-fedora-thing") }}

dnf-utils

URL schemas

{{ track("track-from-our-repo-without-extension") }}

lxqt

{{ custom_track("your-impl-url", "your-track-name-without-extension") }}

blendos-base-t2

{{ reference("folder", "page") }}

bpkg

Container Registries

{{ dockerhub("author", "image") }}

* If the image has no author (r/_/container), set the author to library.

library/archlinux

{{ ghcr("author", "image") }}

Ast3risk-ops/archiver

{{ quay("author, "image") }}

toolbx/ubuntu-toolbox

Git Forges

{{ github("user", "repo") }}

blend-os/blendos

{{ gitlab("user", "repo", "subgroup", "subgroup1") }}

* subgroup and subgroup1 are optional arguments.
* Used as: gitlab.com/user/subgroup/subgroup1/repo
* They both default to nothing.

gitlab-org/gitlab

{{ codeberg("user", "repo") }}

forgejo/forgejo

{{ blendgit("user", "repo", "subgroup", "subgroup1") }}

* subgroup and subgroup1 are optional arguments.
* Used as: git.blendos.co/user/subgroup/subgroup1/repo
* They both default to nothing.

blendos/website

{{ sourcehut("user", "repo") }}

* For user, do not put the ~, that is added for you.

~libreboot/lbmk

CSS classes#

CSS classes you can use:

extra.css

/* .icon classes are computed using https://svg-colorizer.pages.dev
.icon-x-misc classes are for multi-color images and icons. 
.icon-x classes are for monochrome images and icons */

.icon-white {
    filter: invert(100%) sepia(2%) saturate(0%) hue-rotate(148deg) brightness(102%) contrast(106%);
}

.icon-blend-misc {
    filter: brightness(0) saturate(100%) invert(63%) sepia(95%) saturate(356%) hue-rotate(115deg) brightness(85%) contrast(88%);;
}

.icon-link-misc {
    filter: invert(60%) sepia(73%) saturate(415%) hue-rotate(117deg) brightness(91%) contrast(94%);
}

.icon-link {
    filter: brightness(0) saturate(100%) invert(60%) sepia(73%) saturate(415%) hue-rotate(117deg) brightness(91%) contrast(94%);
}

.info {
    color: #00B8D4;
}

.tip {
    color: #00BFA5;
}

.green {
    color: #00C853;
}

.blend {
    color: #21af90;
}

.orange {
    color: #FFA724;
}

.red {
    color: #ff0000;
}

.mt-1 {
    margin-top: 0.1em;
}

.mega {
    color: #D9272E;
}

.yellow {
    color: #FFD600;
}

.pink {
    color: #FF00DE;
}
.purple {
    color: #ad05ad;
}

.red {
    color: #FF1744;
}

.text-lg {
    font-size: large;
}

.ccc {
    display: flex;
    align-items: center;
    justify-content: center;
}

.circle {
    border: 1px solid white;
    border-radius: 100px;

}

.windows {
    color: #0078d6;
}

.warning {
    color: #ff9100;

}

.wide-table {
    width: 100%;
}

You can apply CSS to a whole block like this:

some text
{ .yellow }

some text

to icons:

:material-cog:{ .yellow }

or even to bits of text:

Hi this text is <span class="yellow">**yellow**</span> but this text is normal!

Hi this text is yellow but this text is normal!

Tables too:

| 1                                    | 2   |
| ------------------------------------ | --- |
| I HATE MARKDOWN TABLES 󰩳 { .yellow } | a   |

1	2
I HATE MARKDOWN TABLES	a

as well as lists:

1. 󰩳 a
{ .someclass }
1. 󰩳 b
{ #id }

a
b

Extra features in attr_list

We use a fork of attr_list to support lists and tables. More info is here.

Contributing#

Git Structure#

Mirroring#

Current (ish) stats#

Procedure#

Notes#

Docs#

Rules#

Local Development#

Writing#

Admonitions (admonition)#

Emojis/Icons (emoji)#

CSS in Markdown (attr_list & pm_attr_list)#

Markdown in HTML (md_in_html)#

Code Snippets (snippets)#

Keybinds (keys)#

Inline Syntax Highlighting (inlinehilite)#

Automatic Links (magiclink)#

Javascript#

Macros#

CSS classes#

Admonitions (`admonition`)#

Emojis/Icons (`emoji`)#

CSS in Markdown (`attr_list` & `pm_attr_list`)#

Markdown in HTML (`md_in_html`)#

Code Snippets (`snippets`)#

Keybinds (`keys`)#

Inline Syntax Highlighting (`inlinehilite`)#

Automatic Links (`magiclink`)#