CtrlK
BlogDocsLog inGet started
Tessl Logo

orchardcore-docs-writer

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.

74

Quality

91%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

OrchardCore Docs Writer

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

SectionPath under src/docs/
HomeREADME.md
Getting startedgetting-started/
Guides (tutorials)guides/<name>/README.md
Key topicstopics/<topic>/README.md
Module referencereference/modules/<Name>/README.md
Releasesreleases/
Contributingcontributing/

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

  1. Create src/docs/reference/modules/<Name>/README.md (no OrchardCore. prefix) with the # Name (OrchardCore.Name) header.
  2. Link it from src/docs/reference/modules/README.md (the module index).
  3. Add a nav: entry in mkdocs.yml under the right category (CMS Modules / Core Modules / Content Parts / …).
  4. 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

ItemValue
GeneratorMkDocs + Material for MkDocs
Configmkdocs.yml (root)
Docs dirsrc/docs
Depssrc/docs/requirements.txt
Servepython -m mkdocs serve
Buildpython -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
Repository
OrchardCMS/OrchardCore
Path

.agents/skills/orchardcore-docs-writer/SKILL.md

Commit

b0e1e44

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill