Contributing to Uberspace 8 Lab¶

Help others run software on Uberspace 8: report a problem, improve a guide, or write a new one. Small fixes are welcome, and you do not need to install anything locally to contribute through Codeberg.

Report a problem¶

Use the issue button on a guide or open an issue. Name the application and explain what happened and what you expected. Include relevant commands or errors, with passwords and other secrets removed. You do not need a proposed fix, special title format, or labels.

Fix a guide¶

Edit its docs/guide_<appname>.md file in your fork and open a pull request. Explain what changed and how you checked it. You can use Codeberg's web editor. An issue first is optional; for larger changes it can help coordinate work. Maintainers will help with formatting and review feedback.

Add a guide¶

Copy docs/meta/guide_boilerplate to docs/guide_<appname>.md.
Fill in the metadata, add a logo under docs/_static/images/guides/, and replace the example content. Remove optional sections that do not apply.
Test the instructions on a fresh Uberspace 8 Asteroid and record the versions.
Open a pull request describing what you tested and any remaining questions.

Use a clear title and commit message; no prefix is required. Maintainers handle labels. After review, your contribution appears in the Hall of Fame. New guides and substantial edits can earn a goodie. If possible, stay available to help keep your guide working.

What a guide needs¶

The boilerplate supplies the metadata and shared header. Keep these fields: render_macros: true, title, logo, authors, tags, website, license, and tested with quoted app and uberspace versions.

Every author needs a name and an email address or website/profile URL. These details are public: the Hall of Fame links to the URL when supplied, otherwise to the email address. organization is optional.

Use existing tags from mkdocs.yml → extra.tag_descriptions, or add a short description there for a new tag.

Keep the shared header first, followed by a short introduction, then these sections in order. Omit optional sections when they do not apply.

Section	When needed
Prerequisites	Optional; explain required knowledge in a note before or within this section
Installation	Required; working installation steps
Configuration	Optional
Tuning	Optional
Debugging	Optional
Updates	Required; update steps and a note linking to releases or an update feed
Further Reading	Optional

Exact separator lengths and stock wording are not required.

Write in clear English for readers with basic shell knowledge. Explain unusual steps and flags, use portable paths such as /var/www/virtual/$USER/html/, and show relevant output. Use Uberspace's mariadb / mariadb-dump commands and my_print_defaults client for database credentials. Explain destructive steps and changing default passwords.

Use console-remote fences for server commands and console for local commands. The usual examples are [isabell@moondust ~]$ and [localuser@localhost ~]$. Use a language fence for configuration files. Link to the Uberspace Manual for shared concepts instead of repeating its instructions.

Admonitions¶

Use Material admonitions for information that deserves attention without interrupting the main flow of an article. Keep the main procedure in regular prose and do not repeat nearby content just to fill a box.

A standard admonition starts with !!!. Indent its content by four spaces:

!!! warning "Back up your data before deleting it"

    Explain the risk and how the reader can avoid it.

Use ??? for optional details that should start collapsed, or ???+ when the details should start expanded. Long worked examples are good candidates:

??? example "Show the complete configuration"

    ```yaml
    option: value
    ```

Nest a box by indenting it within the parent box. Use nesting sparingly and only when the nested information belongs exclusively to the parent context:

!!! note "Outer context"

    General information.

    !!! tip "Nested advice"

        Optional advice about the outer context.

Add inline after the type to place a short box to the left of the content that follows it, or use inline end to place it to the right. Declare the box before that content. Use both alignments selectively to vary long page layouts, but do not force long explanations, critical warnings, or wide code and tables into an inline box. Inline boxes automatically use the full width when the viewport is too narrow:

!!! tip inline end "Short advice"

    Keep inline content concise.

This paragraph is rendered beside the box when enough space is available.

Choose the type by meaning, not by preferred color or icon:

Type	Use
`note`	Supplementary clarification or nuance
`abstract`	A summary, overview, or checklist
`info`	A neutral fact, constraint, or status
`tip`	Optional advice, a shortcut, or a best practice
`success`	An expected successful result or verified outcome
`question`	A frequently asked question or common misconception
`warning`	A likely configuration, security, or availability problem
`failure`	A failed outcome or explanation of an error
`danger`	A destructive or irreversible action, including data loss
`bug`	A known defect and, when available, its workaround
`example`	A worked example or extended transcript
`quote`	A sourced quotation

Use canonical lowercase type names. Give every box a concise, descriptive title in sentence case, without a trailing colon or decorative bold markup. Do not use empty titles, deprecated aliases, unsupported custom types, or admonitions as authoring TODOs.

Optional local checks¶

Install uv, then run:

uv sync --frozen
uv run -- python hooks/check_guide.py docs/guide_appname.md
uv run -- mkdocs serve --strict

The checker also accepts --all, --staged, or --changed (committed changes against main; use --base REVISION for another base).

With Task installed, task check runs guide checks, unit tests, and a strict site build. task lint runs the optional local linters; task hooks:install installs Git hooks if you want them. Neither is required to submit a contribution. Automated PR checks report errors and maintainers use the review checklist to assess the instructions themselves.

Code of conduct¶

Be excellent to each other.

Boilerplate¶

---
render_macros: true
title: AppName
logo: _static/images/guides/AppName.png
authors:
  - name: Your Name
    # Supply email or url (both are welcome); used publicly in the Hall of Fame.
    url: https://your-website.com
tags:
  - tag1
  - tag2
  - tag3
website: https://example.com/appname
license: AGPLv3
tested:
  app: "1.0.0"
  uberspace: "8.0.0"
---

{% include 'guide_header.md' %}

Short description of the application.

----

!!! note

    For this guide you should be familiar with the basic concepts of:

    * [PHP](https://u8manual.uberspace.de/lang_php/)
    * [MariaDB](https://u8manual.uberspace.de/database_mariadb/)

## Prerequisites

Describe the runtimes and versions this application needs.

You'll need your MariaDB credentials:

```console-remote
[isabell@moondust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword
```

## Installation

Step-by-step installation instructions...

```console-remote
[isabell@moondust ~]$ cd /var/www/virtual/$USER/html/
[isabell@moondust html]$ wget https://example.com/latest.zip
```

## Configuration

Post-installation configuration steps...

## Tuning

How to make your installation really fly 🚀

## Debugging

Where to look when things are not working as expected.

## Updates

!!! note

    Check the [release page or update feed](https://github.com/example/app/releases.atom) regularly.

Instructions for updating...

## Further Reading

Optional links for debugging, advanced configuration, and deeper documentation:

- [Official documentation](https://example.com/docs): application docs and configuration reference
- [Community support](https://example.com/community): forum or chat for troubleshooting