Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions .claude/skills/docs-new-page/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
name: docs-new-page
description: Drafts new documentation content, as one or more new pages from the matching templates in `templates/`, as additions to existing pages, or both. Use when the user asks to create, write, draft, add to, or start new documentation pages, files, or content.
user-invocable: true
---

Draft new content by following these steps:

1. Check whether the user has provided source material for the content. If material is missing, ask for it in a single prompt before continuing:
* Links, such as Jira tickets or Confluence pages
* Pasted content, such as specs, notes, a Slack thread, a transcript, a draft, a README, code or config snippets, or screenshots

If the user provides a link, read it only if you have a tool that can access it. If you can't access it, say so and ask the user to paste the content.
2. Explore `content/en/docs/` and decide whether the content needs new pages, additions to existing pages, or both, and where each belongs (if it isn't clear, add it to the plan as an open question). Read the section's `_index.md` and nearby pages to match their conventions.
3. Search `content/en/docs/` for the content's main terms. Ignore the versioned folders for older Mendix versions (`refguide10`, `howto9`, and so on) unless the user says the page is for an older version. If a page already covers the entire topic, add to the plan the question of whether to update that page instead. If a page covers part of it, link to that page instead of repeating the covered content, and add to the plan the question of whether the missing content belongs on that page or on a new one.
4. For each new page, read `templates/README.md` to choose the appropriate template, then read that template from `templates/`. If only `general-page-template.md` fits a page, say so in the plan and ask whether to base its structure on sibling pages. For additions to an existing page, follow that page's structure.
5. Present a plan to the user for confirmation or adjustments. List each new page with its template, location, file name, and sections. List each existing page you will change with what you will add and where. Include the source material you will use. Put the open questions from steps 2 to 4 in the plan, and ask them together in one prompt. If the user hasn't said, also ask whether a release note is needed. Don't fill in missing or ambiguous information. Ask for it.
6. Create each new file based on its template. Add the planned content to existing pages in place.
7. Clean up each new page's template as described in the Content Creation Workflow in CLAUDE.md, and uncomment any optional front matter fields the page needs. Compare the optional sections with the nearby pages from step 2, and delete the ones that most of those pages don't have. If nearby pages have a section that the source material doesn't cover, don't fill it in. Ask the user for the information in a single question, and delete the section if they have none.
8. Complete the introduction and the remaining sections of each new page. Add images only if the user provides them. Where an image is needed and none is available, leave out the `figure` shortcode and list the location in your final summary.
9. Compare the files you created or changed with the input the user provided, and give the user a summary of what you did. Flag any input you left out and why. Search sibling pages and flag anything in other files that the new pages make outdated (such as labels or dates) and any conflicts with the new pages. Note any pages that need a link to the new pages. Prioritize technical accuracy. If it isn't clear which source to trust, ask the user.
10. Verify that any linked pages exist in the repo. Link to the related pages found in step 3, and link the new pages to each other where relevant.
11. Run the `docs-copyedit` and `docs-alt-text` skills on each new page and on the content you added to existing pages.
12. Run the `docs-pr-review` skill.
3 changes: 2 additions & 1 deletion .github/copilot-instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ Search the tree to understand where your topic belongs before creating a new fil
* **Terminology** – Capitalize product names (Mendix Portal, Studio Pro, Team Server); use “microflow”, “nanoflow”, etc. consistently. Never use e.g. or i.e.
* **Text formatting** – Reserve bold for UI labels, button names, menu items, or other interface text, or for introductions in list items. Don't use italics except to refer to titles and sections. Use wording or alert shortcodes for emphasis; don't use text formatting for emphasis. Use code font only to wrap literal code, filenames, paths, or command-line input. Use `<kbd>` for keyboard shortcuts.
* **Headings** – H1 is generated from the front‑matter title. Subsequent headings increment by one level at a time. Don't use bold or italics as a replacement for headings. Use title case. Never start headings with numbers.
* **Subsections** – A subsection is the content under a heading one level below its section, such as an H3 under an H2. Add one only for two or more parts that each need a paragraph or more. For a set of options or components that contain figures or tables, use one subsection per member instead of a list or table. Keep procedure steps in a numbered list, even with figures. A linked part can be shorter or stand alone if it has an anchor ID.
* **Lists and tables** – Bullet lists use asterisks; ordered lists use numbers followed by a period. If there are more than three data points per item, use a table instead. Use the same syntax and structure for all list items in a given list. Use complete sentences to introduce lists and tables, not partial sentences completed with the list items.
* **Indentation** – Use four spaces to indent content—for example, to create a sub-list or nest an image or code block in a list. Alerts are an exception: don't indent alert lines but do omit preceding blank line.
* **Links** – Use absolute paths starting with a leading slash (`/deployment/`). Use descriptive link text such as the page title, not “click here”. To link to a heading, add an anchor ID (`{#anchor-id}`) next to the heading and use that ID in the URL (for example, `[Section title](/path/to/page#anchor-id)` to link to a heading in another page or `[Section title](#anchor-id)` to link to a heading in the same page).
Expand Down Expand Up @@ -125,7 +126,7 @@ For comprehensive shortcode examples and edge cases, read `community-tools/contr

If asked to create new content:

1. Read the appropriate template from `templates/`: `how-to-template.md`, `reference-template.md`, `marketplace-component-page-template.md`, or `release-notes-template.md`
1. Read `templates/README.md` to choose the appropriate template, then read that template from `templates/`
2. Create the new file based on the template
3. Remove comment lines (`#`) from the template
4. Follow the editorial workflow above
Expand Down
5 changes: 3 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ When instructions conflict, follow this order of precedence:

### Critical Constraints

* Edit existing files in place using the Edit tool. Do not create new files unless explicitly requested.
* Edit existing files in place using the Edit tool. Do not create new files unless explicitly requested. When a new file is requested, use the `docs-new-page` skill.
* Preserve meaning and intent. Make the smallest set of edits that fully resolves the request.
* Never add product claims, technical behavior, ticket numbers, or release facts unless explicitly requested and sourced from provided content.

Expand Down Expand Up @@ -62,6 +62,7 @@ Before creating a new file, use Glob to explore the directory structure and unde
* **Terminology** – Capitalize product names (Mendix Portal, Studio Pro, Team Server); use "microflow", "nanoflow", etc. consistently. Never use e.g. or i.e.
* **Text formatting** – Reserve bold for UI labels, button names, menu items, or other interface text, or for introductions in list items. Don't use italics except to refer to titles and sections. Use wording or alert shortcodes for emphasis; don't use text formatting for emphasis. Use code font only to wrap literal code, filenames, paths, or command-line input. Use `<kbd>` for keyboard shortcuts.
* **Headings** – H1 is generated from the front‑matter title. Subsequent headings increment by one level at a time. Don't use bold or italics as a replacement for headings. Use title case. Never start headings with numerals.
* **Subsections** – A subsection is the content under a heading one level below its section, such as an H3 under an H2. Add one only for two or more parts that each need a paragraph or more. For a set of options or components that contain figures or tables, use one subsection per member instead of a list or table. Keep procedure steps in a numbered list, even with figures. A linked part can be shorter or stand alone if it has an anchor ID.
* **Lists and tables** – Bullet lists use asterisks; ordered lists use numbers followed by a period. If there are more than three data points per item, use a table instead. Use the same syntax and structure for all list items in a given list. Use complete sentences to introduce lists and tables, not partial sentences completed with the list items.
* **Indentation** – Four spaces for sub-lists and nested content. Alerts in lists are an exception: don't indent alert lines but do omit preceding blank line.
* **Links** – Link using the target page's `url` front matter field, not its file system path (e.g., `/deployment/` from front matter, not `content/en/docs/deployment/_index.md`). Use descriptive link text such as the page title, not "click here". To link to a heading, add an anchor ID (`{#anchor-id}`) next to the heading and use that ID in the URL (for example, `[Prerequisites](/deployment/mendix-cloud/#prerequisites)` to link to a heading in another page or `[Prerequisites](#prerequisites)` to link to a heading in the same page).
Expand Down Expand Up @@ -140,7 +141,7 @@ Less common shortcodes (`button`, `expandable-table`, `youtube`, `vidyard`, `swa

If asked to create new content:

1. Read the appropriate template from `templates/`.
1. Read `templates/README.md` to choose the template that matches the content type, then read that template.
2. Use Write tool to create the new file based on the template.
3. Remove the guidance comments from the template: `#` comments and inline comments in the front matter, and `[//]: #` comments in the body. Complete `title`, `url`, and `description`.
4. Follow the editorial workflow above.
Expand Down
12 changes: 12 additions & 0 deletions templates/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Choosing a Template

Go through the questions in order and use the first template that fits. Each template's opening comment says more about when to use it.

1. Is the page an `_index.md` file that introduces a section and lists its child pages? Use `section-index-template.md`.
2. Is the page release notes?
* Released by version: use `release-notes-version-template.md`.
* Released by date: use `release-notes-date-template.md`.
3. Does the page guide readers through steps to reach a goal? Use `how-to-template.md`.
4. Does the page document a platform-supported Marketplace component, such as a module, widget, or connector? Use `marketplace-component-page-template.md`. For AWS connectors, use `marketplace-aws-connector-page-template.md`.
5. Does the page document the properties of a Studio Pro element? Use `reference-template.md`.
6. Does none of the above fit? Use `general-page-template.md`. Read sibling pages in the same folder for terminology and level of detail, and choose the other headings to fit the topic.
34 changes: 34 additions & 0 deletions templates/general-page-template.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
title: "{Page Title}"
url: /{section}/{page-name}/ # Match the URL pattern of sibling pages (for example, /refguide/session-management/)
#linktitle: Optional. If the title is longer than 40 characters, add a short title for the left navigation
#weight: Optional. Lower numbers appear first among sibling pages.
description: "Describes {the topic}." # Start with Describes, for example, "Describes the {topic}" or "Describes how {topic works}"
---

[//]: # "Use only when no other template fits. Text in {braces} is a placeholder; replace it. Headings without braces are literal. Use only the elements that apply, and match sibling pages."
[//]: # "Read sibling pages in the same folder for terminology, level of detail, and any heading that most of them share. Choose the other headings to fit your topic."

## Introduction

{Describe what the topic is and why it matters to the user.}

## {Section Title}

[//]: # "Add the sections the topic needs. Structure varies by topic, so use a heading from sibling pages only when most of them share it."

{Explain this part of the topic.}

[//]: # "Optional: Add an image or code block only when it does something the text can't. Use an image when the reader needs to recognize a screen or see how parts relate, and a code block for literal code or settings the reader copies. Most paragraphs need neither."

### {Subsection Title}

[//]: # "Optional: Use subsections only where the topic has parts that each need a paragraph or more, such as a detail, an alternative, an example the reader can skip, or a common problem and its solution. For other cases, see the Subsections rule in CLAUDE.md."

{Describe the detail, alternative, example, or problem and solution.}

## Read More

[//]: # "Optional: List supplementary links only. Don't repeat cross-references used earlier in the page."

* [{Link title}]({URL}) – {Explanation, if needed, especially for third-party links.}
47 changes: 27 additions & 20 deletions templates/how-to-template.md
Original file line number Diff line number Diff line change
@@ -1,47 +1,54 @@
---
title: "Enter the title of the document - this should be unique to aid Google indexing"
#url: Set the relative URL of the document; after the name of the main directory/product the document is in, use the document title; example for document titled my-new-page.md, in refguide directory: /refguide/my-new-page/
#linktitle: Enter a short title to be used in the left side menu; increases readability and navigation through the menu
#weight: Enter the position of the document compared to other 'child' documents at the same level; number by 10 (for first), 20, 30, etc. for easy ordering of other documents in the future if necessary; don't add brackets or quotation marks
#description: "Set a description with a maximum of 140 characters; this should describe what the goal of the document is, and it can be different from the document introduction; this is optional, and it can be removed"
#draft: Set to true if page should not appear in production
title: "{How-to Title}" # Start with a bare infinitive and name what the reader accomplishes (for example, Set Up Anonymous User Security)
url: /{section}/{page-name}/ # Match the URL pattern of sibling pages (for example, /howto/security/set-up-anonymous-user-security/)
#linktitle: Optional. If the title is longer than 40 characters, add a short title for the left navigation
#weight: Optional. Lower numbers appear first among sibling pages.
description: "Describes how to {task}."
---

[//]: # "Use for step-by-step guides that help readers reach a goal. Text in {braces} is a placeholder; replace it. Headings without braces are literal. Use only the elements that apply, and match sibling pages."

## Introduction

{Describe what this how-to will cover and what the user will learn.}
{Describe what problem this how-to solves and why it matters to the user.}

[//]: # "Optional: Keep the following list when the how-to covers two or more distinct tasks or outcomes. Omit it when the introduction already states the single goal. Make each item a concrete task outcome (such as create, build, or configure)."

This how-to teaches you how to do the following:
This how-to shows you how to do the following:

* Create...
* Build...
* Configure...
* {Outcome 1}
* {Outcome 2}

## Prerequisites

{If there are no prerequisites, leave this section out}
[//]: # "Optional: Keep this section when the steps depend on something the reader needs first, such as a software version, an existing app or module, access rights, a required configuration, or another how-to or documentation page. List only what the steps require. Omit the section if there are none. Don't list baseline knowledge."

Before starting this how-to, make sure you have completed the following prerequisites:
Before starting this how-to, make sure you have the following:

* {Prerequisite 1}
* {Prerequisite 2}

## {Title of Section Using Present Participle Verb/Gerund}
## {Section Title}

[//]: # "Start the heading with a gerund that names the task (for example, Setting Up Security). Make one section for each distinct stage of the task, with its own steps. Add or remove sections as the task requires."
[//]: # "Optional: Add an image under a step where the reader needs to recognize a screen, dialog box, or result. Don't add one for every step."

To {do this task}, follow these steps:

1. {Step 1}

{{< figure src="/attachments/{path}/{image-name}.png" alt="{Describe the image.}" >}}

2. {Step 2}

{{< figure src="/attachments/rest-of-image-path/image-name-and-extension" >}}
### {Subsection Title}

### {Title of Sub-Section}
[//]: # "Optional: Use a subsection for a sub-task with its own steps, an alternative approach, an example the reader can skip, or a common problem and its solution."

{Use sub-sections for more detail.}
{Describe the sub-task, alternative approach, example, or problem and solution.}

## Read More

* {Link 1}
* {Link2} – {an explanation when necessary especially if this is a third-party link}
[//]: # "Optional: List supplementary links only. Don't repeat cross-references used earlier in the page."

{Make sure this section contains a bulleted list only with explanations where necessary. Do not just repeat cross-references you used throughout the document, but list useful supplementary links here.}
* [{Link title}]({URL}) – {Explanation, if needed, especially for third-party links.}
Loading
Loading