← All guides Qalarc
On this page
Qalarc Guides · Contribute

How to Submit a Guide

2026-11-18 studio #meta
Guides here document things people actually built and ran — measured, honest, and maintained in the open. This page explains the format, the badges, the PR process, and the few rules we hold every guide to.

What we're looking for

The bar is simple: you built it, you ran it, you can show it. Good submissions look like our starter guides — a working setup, the honest numbers, the things that broke, and the fix. Reviews of gear you've never touched, listicles, and SEO filler don't fit, no matter how well written.

Format requirements

A guide is one self-contained HTML file plus one entry in the index JSON. Start from the template — it already has the reading layout, TOC, footnotes and comments wired up:

Open the guide template →

RequirementDetail
Fileguides/<slug>.html — lowercase-hyphen slug, matches the JSON entry
BaseCopy guides/guide-template.html; keep its structure (topbar, TOC, 680px article, footnotes, related, comments)
SectionsEvery <h2> gets an id — both TOCs build from them
Footnotes<sup class="fnref"> refs in the text link to #fn-N entries in the notes list (which sits above the comments)
Reading widthDon't widen the 680px column; long code blocks scroll horizontally
MetaTitle, meta description ≤160 chars, canonical URL, date, author badge, tags, read time

Then add the index entry to guides/data/guides.json:

{
  "slug": "your-guide-slug",
  "title": "Your Guide Title",
  "tags": ["linux", "hardware"],
  "date": "2026-11-18",
  "author": "community",
  "abstract": "Two sentences — this is what shows on the list page.",
  "relatedProjects": ["a-project-slug"],
  "relatedGuides": ["another-guide-slug"]
}

Tags come from the pill set — hardware · local-ai · games · web · tools — plus a couple of free-form tags for specificity (e.g. linux, shaders). If your tags don't fit a pill, say so in the PR; new pills happen when there's a cluster.

Studio vs community badges

Every guide carries exactly one badge next to its date:

BadgeWhoMeaning
studioQalarc teamWritten and maintained by the studio; the numbers come from our own machines
communityExternal contributorsWritten by you, credited to you, reviewed by the studio before merging

Community authors keep credit and can keep maintaining their guide — later fixes go through the same PR route and list you in the guide's notes.

The PR process

Guides live in the open repository behind qalarc.com, so submission is a GitHub pull request:

  1. Fork the qalarc.ai repository (link on the GitHub org page; if you can't find it, email [email protected] and we'll point you at it).
  2. Branch: git checkout -b guide-your-slug
  3. Add your files: guides/your-slug.html (from the template) and the JSON entry in guides/data/guides.json.
  4. Preview locally: serve the repo root (python3 -m http.server) and open /guides/index.html — your guide should appear in the list with its abstract, badge and tags, and its "Read guide →" link should work.
  5. Open the PR titled guide: <your slug> with a one-paragraph description: what you built, on what hardware, and anything the reviewer should verify.

Review checks the technical accuracy, the format above, and the guidelines below. Turns are usually fast; expect at least one round of comments — that's normal, our own guides get corrected publicly too.

Guidelines

One rule with no exceptions: guides document things you actually ran. Everything else here is negotiable; that isn't.
Ask the Qalarc guide