OrchardCore Docs Writer

SkillDocs & knowledge

Lets your agent write and edit OrchardCore documentation pages, navigation entries, and docs site setup.

Available today. Use it from your connected AI after setup.

No other account needed.

Connect ahel once, and every AI you use reads what you have installed.

Then ask your AI: use the OrchardCore Docs Writer skill

About this capability

Authors OrchardCore documentation — MkDocs Material pages, module README docs, nav entries, admonitions, tabbed content, and redirects. Use when the user needs to add or edit a docs page, document a new module, build/serve the docs site, or wire a page into the navigation.

What this skill tells your AI

The instructions your AI receives, as published by orchardcms/orchardcore in .agents/skills/orchardcore-docs-writer/SKILL.md and read by ahel’s review.

This skill guides you through writing OrchardCore documentation following project conventions.

Docs are MkDocs + Material for MkDocs. Config: mkdocs.yml at repo root; pages live under src/docs/. The nav is explicit in mkdocs.yml — a new .md file is invisible until you add it to nav:.

Where pages live

Section	Path under `src/docs/`
Home	`README.md`
Getting started	`getting-started/`
Guides (tutorials)	`guides/<name>/README.md`
Key topics	`topics/<topic>/README.md`
Module reference	`reference/modules/<Name>/README.md`
Releases	`releases/`
Contributing	`contributing/`

Module name in the path drops the OrchardCore. prefix: OrchardCore.Title → reference/modules/Title/README.md.

Workflow A: add a page to an existing area

Step 1: Write the Markdown

Create the file under the right section. For a module, use the header convention:

# Title (`OrchardCore.Title`)

Short description of what the module does.

## Section
...

Step 2: Add it to the nav

Edit mkdocs.yml nav: under the matching parent. Format - Page Title: path/to/file.md:

nav:
  - Reference:
      - Modules:
          - Core Modules:
              - Display Management: reference/modules/DisplayManagement/README.md
              - My Module: reference/modules/MyModule/README.md   # added

Step 3: Build / preview

pip install -r src/docs/requirements.txt   # first time (Python 3.11+)
python -m mkdocs serve                      # http://127.0.0.1:8000
python -m mkdocs build                      # static site

Workflow B: document a new module

Create src/docs/reference/modules/<Name>/README.md (no OrchardCore. prefix) with the # Name (OrchardCore.Name) header.
Link it from src/docs/reference/modules/README.md (the module index).
Add a nav: entry in mkdocs.yml under the right category (CMS Modules / Core Modules / Content Parts / …).
If it's a content part, also link from reference/modules/ContentParts/README.md.

Module docs are not auto-discovered from the manifest — every link is manual.

Markdown conventions

Admonitions

!!! note
    A neutral aside.

!!! warning
    Something that can bite.

!!! tip
    A helpful suggestion.

Tabbed content

=== "App.razor"

    ```razor
    <!DOCTYPE html>
    ```

=== "_Imports.razor"

    ```csharp
    @using System.Net.Http
    ```

Code fences

Always tag the language: ```csharp, ```json, ```bash, ```liquid.

YouTube embeds

Use privacy mode — https://www.youtube-nocookie.com/embed/<id>.

Moving / renaming a page

Add a redirect so old links survive. In mkdocs.yml under plugins: redirects: redirect_maps::

redirect_maps:
  'old/path/README.md': 'new/path/README.md'

Quick Reference

Toolchain

Item	Value
Generator	MkDocs + Material for MkDocs
Config	`mkdocs.yml` (root)
Docs dir	`src/docs`
Deps	`src/docs/requirements.txt`
Serve	`python -m mkdocs serve`
Build	`python -m mkdocs build`

Enabled Markdown extensions

Admonitions (!!! type), pymdownx.superfences (code), pymdownx.tabbed (=== "Tab"), pymdownx.snippets (file embed), pymdownx.tasklist, toc with permalinks.

Module header

# <Display Name> (`OrchardCore.<Id>`)

Gotchas

A new page must be added to nav: in mkdocs.yml or it won't appear (build warns about pages not in nav).
Tabbed content needs a blank line after === "Label" and 4-space indentation of the block.
Use repo-relative Markdown links between docs pages (../Placement/README.md), not absolute URLs.
When moving a page, add a redirect_maps entry — broken inbound links otherwise.
Match the module-header convention exactly; the docs are scanned for consistency.

References

references/docs-structure.md — full directory map, nav anatomy, extensions, redirects
src/docs/contributing/contributing-documentation.md (repo) — official guide
mkdocs.yml (repo root) — config + nav
AGENTS.md (repo root) — build commands

Signals

GitHub stars: 8k
Forks: 3k
Last commit: Sep 2026

Advanced

Catalog kind: skill
Gateway key: orchardcore-docs-writer
Source: github.com/orchardcms/orchardcore

github.com/orchardcms/orchardcore

More in Docs & knowledge

canvas-design
Skill · anthropics doc-coauthoring
Skill · anthropics theme-factory
Skill · anthropics agent-architecture-audit
Skill · affaan-m brand-voice
Skill · affaan-m ck
Skill · affaan-m