Contributing to MARWAN docs

MARWAN docs is built from Markdown files kept in git. Every change pushed to the main branch of MARWAN/marwan-docs on git.marwan.ma is published on this site automatically, within minutes. There is no manual render step.

Edit an existing page#

1. Find the file: a page at https://docs.marwan.ma/tech/<name>.html comes from tech/<name>.md.
2. Edit it on git.marwan.ma (open the file, then the edit button), or clone the repository, edit it locally and push.
3. Keep the file name: the URL of every page is indexed by search engines.

Add a page#

1. Create tech/<name>.md, using lowercase words separated by hyphens. It is published at /tech/<name>.html.

2. Start it with front matter:

   ---
   title: Install Unbound DNS on Rocky Linux 9
   description: One sentence that says what the page covers, shown in search results.
   author: Your Name
   date: 2026-11-12
   tags: [dns, unbound]
   ---
   

3. Use ## and ### for sections; they build the "On this page" menu. The title is the only top-level heading.

4. Add the page name to a section in site.yml so it appears in the sidebar and on the home page.

Markdown you can use#

• Code blocks with a language, such as ```bash, and an optional file name: ```{.bash filename="/etc/raddb/clients.conf"}.
• Notes: ::: note, ::: tip, ::: warning or ::: important, closed by :::.
• Diagrams with ```mermaid, tables, and links to other pages (other-page.md).
• Images: put small images next to the page in tech/ and link them by file name.

Slide decks and large files#

Slide decks (PDF and PPTX), photos and other large files are not stored in git. They live on the docs server in /srv/marwan-docs/media/tech/ and are served at the same URLs as the pages. Ask the NOC team to upload them, then show a deck on a page with a slides block:

```slides
pdf: 4-layer2-vlans-stp-lacp-security.pdf
pptx: 4-layer2-vlans-stp-lacp-security.pptx
title: Layer 2 switching
```

More details#

The README explains how publishing works on the server.