On this page
How to Submit a Guide
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.
- How-tos with reproducible steps (Linux setups, self-hosting, local AI, shaders, game tooling)
- Build logs with measurements — "here's what it cost, here's what it does, here's where it's slow"
- Corrections and deep follow-ups to existing guides (submit as a comment first, or a PR diff)
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:
| Requirement | Detail |
|---|---|
| File | guides/<slug>.html — lowercase-hyphen slug, matches the JSON entry |
| Base | Copy guides/guide-template.html; keep its structure (topbar, TOC, 680px article, footnotes, related, comments) |
| Sections | Every <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 width | Don't widen the 680px column; long code blocks scroll horizontally |
| Meta | Title, 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:
| Badge | Who | Meaning |
|---|---|---|
| studio | Qalarc team | Written and maintained by the studio; the numbers come from our own machines |
| community | External contributors | Written 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:
- 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).
- Branch:
git checkout -b guide-your-slug - Add your files:
guides/your-slug.html(from the template) and the JSON entry inguides/data/guides.json. - 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. - 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
- Original content. Written by you, not generated wholesale or copied from your blog/elsewhere. AI-assisted drafting is fine; you verify every claim.
- Disclose affiliate links. Any affiliate link gets a visible
disclosure near its first use (the template has a ready-made
.affiliateblock). Undisclosed affiliate links are an instant reject. - Tag appropriately. Use the pill set honestly; don't tag-stuff for reach.
- Measured, not marketed. Numbers you actually observed, hardware you name, dates you tested. "It feels faster" needs a number next to it.
- Disclose sponsorship. If a vendor paid you or sent hardware, say so in the first section.
- Corrections welcome, forever. The comments section on your guide is part of the guide — when someone proves you wrong, fix the guide and thank them in the notes.
- Respect the reading layout. No autoplaying media, no trackers beyond the site's own first-party analytics.