# Markdown help center (Agent Skill)

> A help center served from markdown files in your repository: category, tag and article pages, ranked search, locale fallback, JSON-LD and sitemap. No CMS.

Page: https://timerise.ai/skills/help-center-markdown

Agent Skill `help-center-markdown`: https://github.com/timerise-ai/help-center-markdown. Category: Content. Runs on Next.js; backend: Repository files, no CMS.

Latest release: v0.2.16 (2026-10-07).

Install: npx skills add timerise-ai/help-center-markdown. Timerise builds it on a brief; the price comes from the brief.

Every product needs a place where customers find answers without writing to support. A help center is the simplest one: articles in categories, a search box, links between them.

The usual way to get one is a CMS or a hosted knowledge base. That means another login, another monthly fee, and content that lives outside your repository, out of step with the product.

This skill builds the help center from markdown files in the repository. An article is a file with a short header. The build renders the landing, category, tag and article pages. Search ranks results and forgives a trailing space or a missing accent. The build fails when an article is unreachable or a link points nowhere. A language without a translation falls back to the default instead of an empty page.

Build a markdown-backed help center in a Next.js App Router app: category folders of frontmatter articles, statically rendered landing, category, tag and article pages, client-side search with ranking and keyboard navigation, locale-aware routing with default-locale fallback, tags with slug identity and per-tag pages, related articles, breadcrumbs, JSON-LD and sitemap entries, plus a content validator for CI. Use when: (1) building or extending a help center, knowledge base, docs section, support articles or FAQ hub from markdown files in the repo, (2) adding article search, tag pages or tag chips, translated articles with fallback, hreflang/canonical rules, related links, or a collapsible article sidebar, (3) the user mentions: help center, knowledge base, docs site, support articles, markdown content, frontmatter, gray-matter, content/help, validate:help, tags, article search, hreflang, i18n content, "help articles". Carries a loader with a CI validator that fails the build on unreachable or malformed articles, search that tolerates trailing spaces, punctuation and diacritics, and tags grouped by slug so every spelling variant reaches one page. Next.js App Router; the content source is a seam behind one getHelpIndex(locale), so a CMS can replace the filesystem. Not a blog skill, not a CMS integration and not docs generated from code.

This skill was written by the engineer who has shipped this module; the earlier implementation it was audited against was a marketing-site help center. The templates hold the requirement as verified properties: the sidebar shows every article of every category, the parser reads every frontmatter shape the corpus uses and the validator fails the build on the ones it cannot, tags group by slug so one label reaches one page however it is spelled, and search ranks a query however it is typed, trailing space and diacritics included. The loader, search and tag suites cover each of those; [references/provenance.md](references/provenance.md) carries the record.

What it builds:
- Category, tag and article pages
- Ranked client-side search
- Locale fallback
- JSON-LD
- Sitemap
- CI content validator

When to use:
- Building or extending a help center, docs section or knowledge base whose articles are markdown files in the repository, on Next.js App Router, with or without multiple locales.

When not to use:
- **A blog**: dated, authored posts are another content model.
- **Docs generated from code** (OpenAPI, TypeDoc): use their generators.
- **A CMS-backed help site** publishing at runtime: the index contract holds, the loader changes; see the CMS note in [extensions.md](references/extensions.md).
- **Marketing pages that happen to be markdown**: reuse the host's renderer.

Non-negotiables:
- Summaries, never articles, cross to the client. `toSummary` / `toSearchDoc` are the only shapes client components accept, so a page carries about a kilobyte per article rather than the whole corpus; the type signatures enforce it.
- `hidden`, not a height cap, on collapsible nav. A height cap clips whatever does not fit and reports nothing; `hidden` renders every link of every category or none, and the shell template uses only that.
- Untranslated pages canonicalise to the default locale and stay out of hreflang and the sitemap, so a fallback page is never indexed as a duplicate; the loader test flags the fallback and the routes read that flag.
- Validation runs in CI. The runtime is forgiving on purpose, dropping bad refs and sorting missing orders last, and `validate:help` fails the build for the author; the validator tests cover unresolved refs, order ties and skipped files.
- Sort by `order`, then title, then slug. Ties left to `readdir` order differ between filesystems, so the same deploy could list articles differently on another build machine; the loader test orders by `order` then title, never by filename, and the validator warns on ties.
- Search trims, tokenises and folds diacritics, over tags and headings as well as title and description, ranked by field. A query is matched however it is typed, trailing space and accents included; the search tests cover each of those and the title-over-description ranking.
- Every chrome string goes through `HelpStrings`. The header, footer and notices switch locale together with the host; the components take their text only from the strings table, and the i18n checklist greps for literals left in JSX.
- Tags are keyed by `tagSlug`, never by spelling. Case, hyphens and plurals drift across authors, so every variant lands on one page; the tag tests merge spellings under one slug and the validator warns on variants and plural pairs.

Not this:
- A blog: dated, authored posts with covers and localized slugs: The sibling [`blog-markdown`](https://github.com/timerise-ai/blog-markdown) skill; a different content model
- Docs generated from code (OpenAPI, TypeDoc): Their generators; link to the output
- A CMS-backed help site with editors publishing at runtime: The index contract still applies, but the loader, static params and validation change; see the CMS note in `references/extensions.md`
- Marketing pages that happen to be markdown: The host's renderer; this module is the navigation, search and locale model around many articles

What to tell your agent:
- Add a help center to this Next.js app from markdown files in content/help: category pages, article pages, search, and a sitemap entry for every article.
- Our docs are markdown files in English and German. Build /help with a locale fallback, so an article missing in German shows the English one instead of a 404.
- Audit our help center: search misses articles, categories sort inconsistently and some tags are spelled two ways.

Agent eval results (newest per agent and prompt):
- Codex CLI (gpt-6.1-sol) on v0.2.16, 2026-10-07: pass (Repository files)
- Gemini CLI (gemini-3.8-flash) on v0.2.16, 2026-10-07: pass (Repository files)
- Claude Code (claude-opus-5-5) on v0.2.16, 2026-10-07: pass (Repository files)

Recent releases:
- v0.2.16 (2026-10-07): Fix release, from scoring the prompt-1 agent eval runs against 0.2.15. The templates are unchanged.
- v0.2.15 (2026-10-07): Fix release, from scoring the prompt-1 agent eval runs against 0.2.14. The templates are unchanged.
- v0.2.14 (2026-10-07): Fix release, from scoring the prompt-1 agent eval runs against 0.2.13. One template defect was fixed; the shipped suite grows from 23 to 27 tests in five files.