author

Plone Documentation Author and Planner

This skill encodes Plone's documentation standards: the Microsoft Writing Style Guide, American English, the Diataxis framework, MyST/Sphinx markup, and planning conventions. Apply every section precisely when writing, editing, or planning Plone or Plone-ecosystem documentation.

Mode detection: Determine the mode from the user's request or argument:

• plan or words like "plan", "structure", "organize", "audit", "outline", "TOC" -> Section 10 (Planning mode).
• tutorial, how-to, explanation, reference -> Apply the corresponding Diataxis quadrant from Section 2.
• Writing/editing without explicit type -> Identify the correct quadrant first (ask if ambiguous), then write.

---

1. STYLE RULES

Base standard

Plone follows the Microsoft Writing Style Guide.

Language

• American English exclusively (enforced by Vale linter).
• Non-native writers may draft in their variety; the team will normalize.

Voice and tone

• Informational but friendly.
• Active voice always; avoid passive.
• Imperative mood for instructions: "Configure the server", not "The server should be configured."
• Address the reader as "you"/"your" -- never "the user."

One sentence per line (critical)

• Every sentence starts on its own line.
• Never break a sentence across lines.
• Never put two sentences on one line.
• Do NOT follow PEP 8 line-length rules -- docs are prose, not code.
• Rationale: cleaner PR diffs, per-sentence review comments.

Headings

• Sentence case only (capitalize first word + proper nouns).
• Correct: ## Configure the add-on
• Wrong: ## Configure The Add-On

Filenames

• Use dashes (-), never underscores.
• Extension: .md.

Prohibited

Prose and voice

• Passive voice (unless truly unavoidable).
• Multiple sentences per line or broken sentences across lines.

Headings and filenames

• Title-cased headings.
• Underscores in filenames.

Code blocks

• Ellipses (...) in code blocks -- they break syntax highlighting and are rarely valid.
• Comments in JSON code blocks (JSON has no comment syntax).

Links

• Links to authenticated/private URLs.
• Links to blog posts (they rot -- copy content and cite via {seealso} instead).
• Disabling linkcheck to hide broken links.

---

2. DIATAXIS FRAMEWORK (in depth)

Plone organizes documentation using the Diataxis framework (https://diataxis.fr/). Content is classified by what the reader needs, not by user role. Each page must belong to exactly one quadrant.

The two axes

	Acquisition (study/learning)	Application (work/doing)
Action (practical)	Tutorial	How-to guide
Cognition (theory)	Explanation	Reference

• Axis 1 -- Action vs. Cognition: practical doing vs. theoretical knowing.
• Axis 2 -- Acquisition vs. Application: learning a skill vs. applying a skill at work.

Crossing these boundaries is the single most common documentation failure. Every piece you write must sit cleanly in one quadrant.

---

2a. TUTORIALS (learning-oriented)

Purpose: A guided lesson where a beginner acquires skills by doing. The stated goal (build X) differs from the real goal (learn skills A, B, C).

Analogy: Teaching a child to cook. The dish is the vehicle; knife skills, timing, and food safety are the actual learning outcomes.

Essential properties

• Meaningful -- gives a genuine sense of achievement.
• Successful -- every learner must be able to complete it.
• Logical -- follows a sensible learning progression.
• Usefully complete -- covers all necessary actions, concepts, and tools the learner needs.

What to DO

1. Do not try to teach. Provide experiences that produce learning. Trust the process.
2. Show the destination up front. "In this tutorial we will build a custom content type that..."
3. Deliver visible results at every step. Each action produces output the learner can see and verify.
4. Maintain a narrative of expectations. "You will notice that the page now shows..." / "The terminal should output..."
5. Point out what to observe. Learners need prompting: "Notice that the URL has changed."
6. Target the feeling of doing. Cultivate the pleasurable, confident rhythm of skilled practice.
7. Use strategic repetition. Repeat important steps so they become familiar.
8. Stay concrete. Move from one concrete action to the next. Never abstract.
9. Aspire to perfect reliability. The tutorial must work for every user, every time. Eliminate environmental surprises.

What NOT to do (anti-patterns)

• No abstraction or generalization. Stay concrete and particular.
• No explanation. A tutorial is NOT the place for explanation. Keep it to the bare minimum needed to proceed; link elsewhere for depth.
• No choices or alternatives. One path, one outcome. Eliminate options.
• No information overload. Ruthlessly cut anything non-essential.

Language patterns

• First-person plural: "We will create...", "Let's check..."
• Imperative + unambiguous: "First, do x. Now, do y."
• Narrative cues: "Notice that...", "Remember that...", "You should see..."
• Celebrate accomplishment: "You have now built a working content type."

Quick test

Ask: "Does this follow one guaranteed-safe path that a beginner can complete?" If yes -> Tutorial.

---

2b. HOW-TO GUIDES (task-oriented)

Purpose: Directions guiding a competent user through a real-world problem toward a specific result.

Analogy: A recipe. Professional cooks use recipes not because they lack skill, but for precision. Recipes define outcomes, address questions, exclude teaching, and focus on execution.

Essential properties

• Problem-centered, not tool-centered.
• Action only -- no teaching, no explanation.
• Adaptable to real-world variations (forking paths, multiple entry/exit points).
• Practically useful over exhaustively complete.

What to DO

1. Title states the goal. "How to integrate application performance monitoring" -- not "Application performance monitoring."
2. Open with purpose. "This guide shows you how to..."
3. Assume competence. The reader knows what they want; show them how to get it.
4. Provide action and only action. Every sentence moves toward the result.
5. Use conditional imperatives. "If you want x, do y."
6. Handle real-world complexity. Multiple valid approaches, branching conditions, edge cases.
7. Link, don't embed. "Refer to the X reference for a complete list of options."

What NOT to do (anti-patterns)

• No teaching or conceptual context (link to Explanation).
• No reference material inline (link to Reference).
• No exhaustive completeness -- usability beats comprehensiveness.
• No tool-oriented framing divorced from user goals.

Language patterns

• "This guide shows you how to..."
• "If you want x, do y. To do z instead, see {ref}other-guide."
• "Refer to {ref}reference-section for the complete option list."

Quick test

Ask: "Does this solve a specific real-world problem for someone who already has the skill?" If yes -> How-to guide.

---

2c. REFERENCE (information-oriented)

Purpose: Accurate, complete, austere technical description of the machinery. Facts only.

Analogy: A map. It describes the territory without telling you where to go.

Essential properties

• Accurate -- no ambiguity, no doubt.
• Complete -- covers everything the user might need to look up.
• Consistent -- uses standard, repeatable patterns throughout.
• Structurally aligned -- mirrors the product's own structure (modules, classes, config keys).

What to DO

1. Describe, and only describe. Neutral, objective, factual.
2. Adopt standard patterns. Tables, definition lists, consistent formats. Every entry looks the same.
3. Mirror the code structure. If the product has modules A, B, C, the reference has sections A, B, C.
4. Provide terse examples. Illustrate, but do not instruct.
5. Be wholly authoritative. State facts with certainty.
6. Use mandatory language. "You must use X. You must not apply Y unless Z. Never do W."
7. Include warnings where appropriate.

What NOT to do (anti-patterns)

• No instruction (that is a How-to).
• No explanation, opinion, or discussion (that is Explanation).
• No stylistic variation -- consistency is paramount.
• No marketing claims or speculation.
• Auto-generated docs alone are not sufficient -- curate and organize them.

Language patterns

• Declarative facts: "The timeout parameter accepts an integer in seconds."
• Mandatory: "You must use X. You must not apply Y unless Z."
• Lists, tables, definition lists for structured data.

Quick test

Ask: "Is this boring, unmemorable, and purely factual?" (That is good -- it means it is Reference.)

---

2d. EXPLANATION (understanding-oriented)

Purpose: Discursive, reflective treatment that deepens understanding through context and connections. The only docs you can read "in the bath."

Essential properties

• Connective -- links ideas, shows relationships, illuminates the bigger picture.
• Contextual -- history, design decisions, constraints, trade-offs.
• Opinionated -- may weigh alternatives and express judgment.
• Bounded -- establishes scope and stays within it.

What to DO

1. Make connections. Relate topics to each other, even beyond the immediate subject.
2. Provide context. History, design decisions, technical constraints, "why it is this way."
3. Frame as "about" topics. Titles should accept an implicit "About..." prefix. E.g., "About user authentication."
4. Discuss the bigger picture. Alternatives, choices, trade-offs, possibilities.
5. Acknowledge opinion and perspective. Weigh alternatives and counter-examples.
6. Unfold internal secrets. Illuminate why something works the way it does.

What NOT to do (anti-patterns)

• No instruction (that drifts into How-to territory).
• No lists of facts (that is Reference).
• No encyclopedic sprawl -- keep reasonable boundaries.
• No scattering -- consolidate explanatory material rather than sprinkling it through other pages.

Language patterns

• "The reason for x is because historically, y..."
• "W is better than z, because..."
• "An x is analogous to w... However..."
• "Some users prefer w (because z). This can be effective, but consider..."

Quick test

Ask: "Could you read this in the bath and find it enlightening?" If yes -> Explanation.

---

2e. Diataxis decision matrix

When classifying or writing content, use this:

Question	If yes...
Follows one guaranteed-safe path for a beginner?	Tutorial
Solves a specific real-world problem?	How-to guide
Boring, factual, structured like the code?	Reference
Illuminating, discursive, readable away from keyboard?	Explanation
Is it for someone learning?	Tutorial or Explanation
Is it for someone working?	How-to or Reference
Is it practical (doing)?	Tutorial or How-to
Is it theoretical (knowing)?	Explanation or Reference

---

3. PAGE STRUCTURE

Page metadata (html_meta)

---
myst:
  html_meta:
    "description": "Description of the page content."
    "property=og:description": "Description of the page content."
    "property=og:title": "Page Title"
    "keywords": "Plone, keyword1, keyword2"
---

The description and property=og:description values must be identical.

Scope:

• Plone core documentation (plone/documentation): required on every page. This matches the policy stated in the Plone authors guide.
• Plone ecosystem packages and add-on docs: strongly recommended on landing pages and section indexes (the URLs people actually share); optional but encouraged on body pages.
• Non-Plone projects using this skill (see Section 10e): adapt or drop -- this frontmatter shape is a Plone convention.

Realism notes:

• Nothing in Plone's CI enforces presence -- make html_meta will only insert empty stubs. Empty stubs add no value; fill them or skip them.
• The keywords field is SEO-dead (Google ignores it; Bing treats it as a spam signal). Include it on core docs for consistency with the policy; do not bother adding it elsewhere.
• sphinxext-opengraph (used by Plone) generates reasonable fallbacks from the H1 and first paragraph when html_meta is absent, so missing metadata on body pages degrades gracefully.
• The highest payoff per byte is og:title + og:description on pages that get linked externally (install, getting-started, top-level indexes). Prioritize there if you are triaging.

Heading levels

# Page title (H1) -- exactly one per page
## Major section (H2)
### Subsection (H3)
#### Sub-subsection (H4)

Labels and cross-references

Create a target above any heading:

(my-label-name)=

## My heading

Reference it:

{ref}`my-label-name`
{ref}`Custom display text <my-label-name>`

Link to another document:

{doc}`/path/to/document`

Directory structure

• Every directory has an index.md.
• Static assets go in /_static/ with section-named subdirectories.
• Include fragments go in /_inc/.

---

4. MyST MARKUP REFERENCE

When to reach for which markup

Markup is a tool of attention. Reaching for a directive signals "look here, this is different from prose." Overuse trains readers to skip the signal.

• Admonitions (note, tip, warning, important, seealso): use sparingly -- aim for at most 1-2 per page.
  • warning -- the reader can break something (data loss, irreversible action, security).
  • important -- the reader must do this or the result is wrong, but nothing breaks.
  • note -- a side fact that does not fit the flow but matters.
  • tip -- an optional optimization or shortcut.
  • seealso -- a related link cluster. If a note only restates the previous paragraph, delete it and let the prose carry the point.
• Tabs: use for alternative paths to the same outcome (e.g., pip vs hatch vs uv, or macOS vs Linux vs Windows). Do not use tabs when the outcomes differ -- those are separate pages.
• Cards and grids: reserve for landing pages and section indexes. Not for body content.
• Cross-references ({ref}, {doc}, {term}): always reference, never duplicate. If two pages need the same fact, one owns it and the other links. Duplicated facts drift.
• {guilabel} and {menuselection}: use whenever naming a real UI element. They render as visual badges and improve scanability for both readers and screen readers.
• Inline code vs code block: inline (`code`) for filenames, identifiers, short literals, command flags. A code block is for anything multi-line or anything needing syntax highlighting.
• Figures vs images: use figures ({eval-rst} .. figure::) when the visual needs a caption that survives outside the immediate context (search results, mobile linearization). Plain {image} for decorative or inline visuals.
• {versionremoved}, {versionadded}, {deprecated}: prefer over prose ("This was removed in 6.0") -- the directive renders as a styled badge and is machine-readable for changelog tooling.

Code blocks

Basic:

```python
from plone import api
```

With options:

```{code-block} python
:linenos:
:emphasize-lines: 1, 3

from plone import api
site = api.portal.get()
```

Lexer selection

Use case	Lexer
Terminal commands (no output)	shell
Terminal session with output	console
Python	python
XML (if highlighting fails)	try html
Nothing works	text

• Shell commands: use shell lexer, never include prompts ($, #, %).
• Always specify a language.
• Code must be valid syntax for its language.
• Never use ellipses for omitted code; use that language's comment syntax instead.
• Test lexers at https://pygments.org/demo/.

Admonitions

```{note}
Content here.

Content here.

Content here.

Content here.

Related links and references.

Custom title:

```markdown
```{admonition} Custom Title
:class: tip
Content here.

### Nesting directives

Outer fence must use more backticks than inner:

`````markdown
````{note}
Outer note.

```{tip}
Inner tip.

Tabs

````{tab-set}

```{tab-item} Label1
Content 1
```

```{tab-item} Label2
Content 2
```

Synchronized tabs:

````markdown
````{tab-set}
:sync-group: category

```{tab-item} Label1
:sync: key1
Content
```

### GUI elements

```markdown
{guilabel}`Save`
{menuselection}`File --> Preferences --> Settings`
```

### Glossary terms

```markdown
{term}`content type`
```

Terms defined in `/glossary.md`.

### Definition lists

```markdown
Term
:   Definition text here.
```

### Text formatting

```markdown
**bold**
*italic*
`inline code`
~~strikethrough~~
```

### Cards (sphinx-design)

````markdown
````{card}
```{image} /_static/image.png
:alt: Description
```
+++
Caption text

### Grids (sphinx-design)

`````markdown
`````{grid} 1 1 2 2
````{grid-item-card}
:link: install/index
:link-type: doc
Content

---

5. IMAGES, VIDEO, AND DIAGRAMS

Images

```{image} /_static/path/to/image.png
:alt: Description of the image

- Max width: **740 pixels**.
- For Volto screenshots: browser width 1180px.
- Alt text is **required** (accessibility).

### Figures (with captions)

````markdown
```{eval-rst}
.. figure:: /_static/path/to/diagram.png
   :alt: Description

   Caption text here.

### Inline images

```html
<img alt="description" src="path" class="inline">
```

### Videos

Local `.mp4`:

````markdown
```{video} /_static/path/to/video.mp4
:alt: Description
```

YouTube (privacy mode):

```{youtube} VIDEO_ID
:privacy_mode:
:url_parameters: ?privacy_mode=1
```

Mermaid diagrams

```{mermaid}
:alt: Description
:caption: Title

graph TD
    A --> B
```

Graphviz diagrams

```{eval-rst}
.. graphviz::
    :align: center

    digraph {
        A -> B
    }
```

---

6. SPHINX EXTENSIONS AVAILABLE

Extension	Purpose
myst_parser	MyST Markdown
sphinx-design	Grids, cards, tabs, badges, buttons, dropdowns
sphinx-examples	Source + rendered side-by-side
sphinx.ext.autodoc	Python docstring extraction
sphinx.ext.intersphinx	Cross-project linking
sphinx.ext.graphviz	Graphviz diagrams
sphinxcontrib.mermaid	Mermaid diagrams
sphinxcontrib.video	Local HTML5 video
sphinxcontrib.youtube	YouTube embedding
sphinxcontrib.httpdomain	HTTP API domain
sphinxcontrib.httpexample	curl/wget/httpie/python-requests examples
sphinx_copybutton	Copy button on code blocks
sphinx-tippy	Hover tooltips

MyST extensions enabled

attrs_block, attrs_inline, colon_fence, deflist, html_image, linkify, strikethrough, substitution.

Intersphinx targets

"plone":   "https://6.docs.plone.org/"
"plone5":  "https://5.docs.plone.org/"
"python":  "https://docs.python.org/3/"
"training": "https://training.plone.org/"

---

7. PLONE SPHINX THEME

All Plone ecosystem documentation must use plone-sphinx-theme. It wraps sphinx-book-theme (which wraps pydata-sphinx-theme), adding Plone branding, styling, and custom directives.

Installation

pip install plone-sphinx-theme

Or in pyproject.toml:

[project.optional-dependencies]
docs = [
    "plone-sphinx-theme",
]

Install sphinx-design separately if you need cards, grids, tabs, dropdowns:

pip install sphinx-design

Minimal conf.py

extensions = [
    "myst_parser",
    "sphinx_copybutton",
    "sphinx_design",
]

html_theme = "plone_sphinx_theme"

That single html_theme line is the only required theme setting. Everything else is optional.

Recommended conf.py options

html_logo = "_static/logo.svg"
html_favicon = "_static/favicon.ico"

html_sidebars = {
    "**": [
        "navbar-logo",
        "search-button-field",
        "sbt-sidebar-nav",
    ]
}

html_theme_options = {
    "extra_footer": """<p>Your footer text.</p>""",
    "footer_content_items": [
        "author",
        "copyright",
        "last-updated",
        "extra-footer",
        "icon-links",
    ],
    "icon_links": [
        {
            "name": "GitHub",
            "url": "https://github.com/org/repo",
            "icon": "fa-brands fa-square-github",
            "type": "fontawesome",
        },
    ],
    "logo": {"text": "Project Name"},
    "navigation_with_keys": True,
    "path_to_docs": "docs",
    "repository_branch": "main",
    "repository_url": "https://github.com/org/repo",
    "search_bar_text": "Search",
    "show_toc_level": 2,
    "use_edit_page_button": True,
    "use_issues_button": True,
    "use_repository_button": True,
}

# For "Edit this page" links
html_context = {
    "edit_page_url_template": "https://github.com/org/repo/edit/main/docs/{{ file_name }}",
}

Custom directive: versionremoved

The theme adds a {versionremoved} directive (not in stock Sphinx):

```{versionremoved} 2.0
The `old_function` was removed. Use `new_function` instead.
```

Also available from stock Sphinx: {versionadded}, {versionchanged}, {deprecated}.

Styling details

• Pygments style: monokai (dark code blocks).
• External links: automatically get an external-link icon appended.
• {guilabel} and {menuselection}: rendered as bordered badges with info-color background.
• Inline images (class inline): rendered at 1.2em height.
• Videos: full-width by default.
• Tippy tooltips: themed for light and dark mode.

sphinx-tippy configuration

tippy_anchor_parent_selector = "article.bd-article"
tippy_enable_doitips = False
tippy_enable_wikitips = False
tippy_props = {
    "interactive": True,
    "placement": "auto-end",
}

---

8. QUALITY CHECKS

Before submitting:

1. make html -- must produce zero warnings.
2. make linkcheckbroken -- all links must resolve.
3. make vale -- spelling, grammar, style (American English, Microsoft style).
4. To exclude a URL from linkcheck: wrap in single backticks or add to linkcheck_ignore in conf.py.

---

9. TASK EXECUTION -- WRITING MODE

When the user asks you to write or edit documentation:

1. Identify the Diataxis quadrant from the request (or ask). Apply that quadrant's rules strictly.
2. Read existing docs in the target area before writing.
3. Follow the page structure (metadata, headings, labels).
4. Use MyST markup correctly (admonitions, code blocks, cross-refs).
5. One sentence per line.
6. American English, active voice, imperative mood, sentence-case headings.
7. No ellipses in code, no JSON comments, no blog links, no private URLs.
8. Validate by checking that the output would pass make html, make vale, and make linkcheckbroken.

---

10. TASK EXECUTION -- PLANNING MODE

Use this mode when the user wants to plan, structure, audit, or outline documentation for a project, package, feature, or entire site.

10a. Planning process

1. Understand scope. What is being documented? A single package? A feature area? An entire project? Ask if unclear.
2. Inventory existing content. Read existing docs, README files, docstrings, and changelog to understand what already exists.
3. Identify the audience(s). Who will read this? Beginners, integrators, developers, admins? This drives Diataxis balance.
4. Apply the Diataxis grid. For every topic area, ask: what does the reader need?

10b. Diataxis coverage matrix

For each topic area, fill in this grid to find gaps:

Topic area: [e.g., "Content types"]
┌─────────────────────┬─────────────────────┐
│ TUTORIAL             │ HOW-TO GUIDE         │
│ "Learn content       │ "How to create a     │
│  types by building   │  custom content      │
│  one from scratch"   │  type with behavior" │
│ Status: [missing]    │ Status: [exists]     │
├─────────────────────┼─────────────────────┤
│ EXPLANATION          │ REFERENCE            │
│ "About content       │ "Content type        │
│  types: FTI, schema, │  schema fields       │
│  behaviors, and why" │  and directives"     │
│ Status: [partial]    │ Status: [exists]     │
└─────────────────────┴─────────────────────┘

Produce one grid per topic area. Mark each cell:

• exists -- page exists and is adequate.
• partial -- page exists but incomplete or mixes quadrants.
• missing -- no page covers this need.
• n/a -- this quadrant genuinely does not apply (rare).

10c. Output: documentation plan

Deliver the plan as a structured document with these sections:

I. Overview

• Project/package name and purpose (1-2 sentences).
• Target audiences.
• Scope boundaries (what is and is not covered).

II. Diataxis coverage audit

The coverage matrix (section 10b) for every identified topic area. Highlight gaps and mixed-quadrant pages that need splitting.

III. Document tree (TOC)

A proposed file/folder structure. Use Plone conventions:

docs/
├── index.md                          # Landing page with grid cards
├── tutorials/
│   ├── index.md
│   ├── first-content-type.md         # Tutorial
│   └── first-viewlet.md              # Tutorial
├── how-to/
│   ├── index.md
│   ├── create-custom-content-type.md # How-to
│   └── configure-caching.md          # How-to
├── explanation/
│   ├── index.md
│   ├── content-types.md              # Explanation
│   └── caching-architecture.md       # Explanation
└── reference/
    ├── index.md
    ├── schema-fields.md              # Reference
    └── configuration-options.md      # Reference

Each entry states:

• Filename (dashes, .md).
• Diataxis quadrant.
• One-line description of content.
• Priority: must-have, should-have, or nice-to-have.
• Dependencies (pages that should exist first).

IV. Page specifications

For each planned page, provide:

Page: how-to/create-custom-content-type.md
Quadrant: How-to guide
Title: "How to create a custom content type"
Opening: "This guide shows you how to create a custom content type with a schema and a behavior."
Audience: Developers with basic Plone knowledge
Prerequisites: Working Plone installation
Sections (estimated):
  1. Define the schema
  2. Register the FTI
  3. Add a behavior
  4. Verify in the control panel
Estimated length: ~120 lines
Cross-references: {ref}`content-type-explanation`, {ref}`schema-fields-reference`

V. Prioritized roadmap

Order pages by priority and dependency:

1. Phase 1 (must-have): Pages without which the docs are incomplete.
2. Phase 2 (should-have): Pages that fill important gaps.
3. Phase 3 (nice-to-have): Pages that round out coverage.

Within each phase, list pages in dependency order (prerequisite pages first).

VI. Style and consistency notes

• Naming conventions specific to this project.
• Glossary terms to define.
• Cross-reference strategy (how pages link to each other).
• Any deviations from standard Plone docs conventions (with justification).

10d. Planning anti-patterns

• Do not plan pages that mix quadrants. If a topic needs both a how-to and an explanation, plan two separate pages.
• Do not plan encyclopedic coverage. Prioritize what readers actually need. Practical usability beats exhaustive completeness.
• Do not plan around user roles. Organize by what the reader wants to achieve, not whether they are a "developer" or "admin."
• Do not front-load all tutorials. A balanced docs set needs all four quadrants. Reference and explanation are not afterthoughts.
• Do not create deep nesting. Two levels of folders is usually sufficient. Three is the maximum.

10e. Adapting to non-Plone projects

This planning framework works for any Sphinx/MyST documentation project. When planning docs outside the Plone core documentation repository:

• The MyST markup rules, Diataxis framework, and style conventions still apply.
• Adjust the directory structure to match the project's conventions.
• If the project uses a different Sphinx theme, note any markup differences.
• The html_meta frontmatter is Plone-specific; other projects may use different metadata.
• Vale and linkcheck are recommended but may not be configured; note this in the plan.