From da190efbcddef351152a0d25039dec1b66c62d15 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Wed, 11 Mar 2026 17:05:11 +0100 Subject: [PATCH 1/3] Add Copilot instructions and prompts --- .github/copilot-instructions.md | 135 ++++++++++++++++++++++++++ .github/prompts/add.prompt.md | 7 ++ .github/prompts/enhance.prompt.md | 5 + .github/prompts/polish.prompt.md | 9 ++ .github/prompts/proofread.prompt.md | 10 ++ .github/prompts/review.prompt.md | 5 + .github/release-notes-instructions.md | 85 ++++++++++++++++ 7 files changed, 256 insertions(+) create mode 100644 .github/copilot-instructions.md create mode 100644 .github/prompts/add.prompt.md create mode 100644 .github/prompts/enhance.prompt.md create mode 100644 .github/prompts/polish.prompt.md create mode 100644 .github/prompts/proofread.prompt.md create mode 100644 .github/prompts/review.prompt.md create mode 100644 .github/release-notes-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000000..1715fdbe4c2 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,135 @@ +# Mendix Documentation Repository + + + +This repository contains the source for the Mendix documentation site, a Hugo-based static website that describes the Mendix low-code platform. Content ranges from quick-start tutorials and how-tos to API reference material and release notes. + +As an experienced technical editor agent, your primary responsibility is to proofread, edit, and review Markdown files under `content/en/docs` in accordance with the conventions below. Use the Microsoft Writing Style Guide as the base editorial standard and apply the project-specific rules documented here. + +## 0 Instruction precedence + +When instructions conflict, follow this order of precedence: + +1. The user's current request. +2. Task-specific prompt files in `.github/prompts/*.prompt.md` when explicitly referenced. +3. Overlay instruction files (for example, `.github/release-notes-instructions.md`) when path-scoped. +4. This file (`.github/copilot-instructions.md`). +5. Existing conventions in nearby pages within the same section. +6. Microsoft Writing Style Guide. + +### 0.1 Default execution mode + +* MUST edit existing files in place unless the user explicitly asks to create new content. +* MUST preserve meaning, chronology, and intent. +* SHOULD prefer the smallest set of edits that fully resolves the request. +* MUST NOT add net-new product claims, technical behavior, ticket numbers, or release facts unless explicitly requested and sourced from provided content. + +## 1. Project overview + +* **What** – Mendix is a low‑code application development platform that lets users visually design, build, test, and deploy web and mobile applications. +* **Who** – Target readers are developers, business analysts, and partners who consume the docs for learning, troubleshooting, and reference. +* **Tech stack** – Site built with [Hugo](https://gohugo.io/), custom theme and shortcodes under `layouts/`. Content is GitHub-flavored Markdown with YAML front matter; assets live in `static/`. + +## 2. Content structure and hierarchy + +The canonical tree is **`/content/en/docs`**. Top‑level directories correspond to major product areas (e.g. `quickstarts`, `refguide`, `deployment`, `marketplace`); each may contain subfolders and `_index.md` files that define section landing pages. + +Typical structure: + +``` +content/en/docs/ +├── _index.md +├── quickstarts/ +│   ├── _index.md +│   ├── hello-world.md +│   └── responsive-web-app.md +├── refguide/ +│   ├── _index.md +│   ├── modeling/ … +│   └── runtime/ … +… +``` + +* **Index files (`_index.md`)** define landing pages or categories. They often use `cascade` to pass metadata to children and may set `type`, `layout`, `no_list`, `description_list` etc. +* Other `.md` files represent individual articles, how‑tos, reference topics, release notes, etc. File names should be simple, lowercase, and hyphen‑separated. + +Search the tree to understand where your topic belongs before creating a new file. + +## 3. Style standards + +* **Guiding manual** – Microsoft Writing Style Guide (https://learn.microsoft.com/style-guide/). Apply grammar, inclusive language, terminology, and formatting rules from that document. +* **Tone** – Clear, concise, active voice; use imperative mood for procedures; second person (you/your) when addressing readers. Keep a conversational, straightforward tone. Present tense. Use American English and write for a global audience. Prefer short, everyday words; avoid or explain jargon. Keep it simple—short sentences and fragments are easier to scan and read, and prune excess words. Avoid marketing language. +* **Terminology** – Capitalize product names (Mendix, Studio Pro, Developer Portal); 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 `` 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. +* **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: To indent an alert within a list, omit the blank line before the alert. Don't indent the lines of the alert. +* **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). +* **Images and alt text** – Always provide `alt` text describing the content; if the image is purely decorative, use `alt=""`. Use W3C guidelines to write alt text. Reference images with the `figure` shortcode (see below). +* **Code** – Use fenced code blocks with language specifier. + +Project‑specific preferences are documented in the templates and in `community-tools` example pages; consult them for tricky formatting cases. + +## 4. Technical implementation details + +### 4.1 Front matter + +All Markdown files begin with YAML metadata. Required fields vary by page type: + +* `title` – Human‑readable page title. +* `url` – Page URL. +* `description` – Summary used for metadata and search snippets. Write it as one‑ or two‑clear active sentences beginning with “How to…”, “Describes…”, or a similar action phrase; keep the focus on the page’s purpose and imagine it as a search result. +* `linktitle` – Optional; short text shown in the left navigation pane. +* `weight` – Optional; numeric ordering among siblings; use increments of 10 to leave room for future inserts. +* `draft` – Optional; set to `true` to exclude from production builds; remember to remove it before publishing. +* `numberless_headings` – Optional; set `true` for release notes and pages where heading numbering is unwanted. +* `cascade` – Optional; used only in `_index.md` files to propagate parameters (e.g. `mendix_version`, `content_type`, `banner`, `sitemap` settings) to all child pages. +* `type`, `layout`, `aliases` – Optional; rarely used for landing pages (see root `_index.md`). + +### 4.2 Shortcodes + +Hugo shortcodes encapsulate reusable components. The ones you will encounter most frequently include: + +* `figure` – Images and screenshots. Attributes: `src` (required), `alt` (required or `""`), `class`, `max-width`, `link`. Always store assets under `static/attachments/...` and reference with `/attachments/...`. + + ```md + {{< figure src="/attachments/quickstarts/part1/3.login.png" alt="Sign in to Studio Pro" max-width="80%" >}} + ``` + +* `alert` – Callouts of type `info`, `warning`, `success`, or `danger`. + ```md + {{% alert color="warning" %}} + This action cannot be undone. + {{% /alert %}} + ``` + +* `button` – Link buttons with `color`, `href`, `text`, and optional `title` attributes. +* `icon` – Inline SVG icons stored in `static/mx-icons` (`name` required, optional `color`) for use in UI descriptions. +* `youtube` / `vidyard` – Embed videos by ID. +* `swaggerui` / `swaggerui-disable-try-it-out` – Render OpenAPI specs. +* `snippet` – Include external code or page content. +* `tabpane` / `tab` – Create tabbed code examples. +* `todo` – Internal draft notes; omitted in production. + +The `community-tools/contribute-to-mendix-docs/markdown-shortcodes.md` page contains comprehensive examples. Review it when adding new types or debugging rendering. + +## 5. Editorial workflow + +1. **Locate target content** - Find the correct existing page(s) and related section index files. +2. **Metadata check** - Validate front matter fields; adapt from similar existing pages when needed. +3. **Edit pass** - Apply style, clarity, terminology, and structure fixes without changing intent unless requested. +4. **Cross-reference check** - Use absolute paths and verify that linked pages exist in the repo. +5. **Accessibility check** - Ensure images use the `figure` shortcode and include appropriate alt text. +6. **Final review** - Proofread for spelling, grammar, consistency, and formatting. +7. **Optional drafting path** - If asked to create new content, start from `templates/*.md` and then follow the same checks above. + +## 6. Standard content template + +Create new pages by copying one of the following templates and removing the comment lines (`#`): + +* **How‑to** – `templates/how-to-template.md` +* **Reference** – `templates/reference-template.md` +* **Marketplace component** – `templates/marketplace-component-page-template.md` +* **Release notes** – `templates/release-notes-template.md` + +For all pages, required sections are front matter and the introduction; other sections vary by content type. \ No newline at end of file diff --git a/.github/prompts/add.prompt.md b/.github/prompts/add.prompt.md new file mode 100644 index 00000000000..2f14a2a80e6 --- /dev/null +++ b/.github/prompts/add.prompt.md @@ -0,0 +1,7 @@ +--- +description: Add new content to a page without rewriting existing content. +--- + +Prompt the user for the new content to add. Determine a suitable place to smoothly integrate the new content into the existing content, with appropriate transitions and formatting, while preserving the original meaning and structure of the page. Avoid making changes to existing content unless necessary for clarity or coherence when adding the new content. + +If the new content introduces redundancy or conflicts with existing content, flag these issues in the chat and suggest ways to resolve them without directly editing the existing content. \ No newline at end of file diff --git a/.github/prompts/enhance.prompt.md b/.github/prompts/enhance.prompt.md new file mode 100644 index 00000000000..6f56699495f --- /dev/null +++ b/.github/prompts/enhance.prompt.md @@ -0,0 +1,5 @@ +--- +description: Edit the text, including reorganization and rephrasing. +--- + +Perform holistic improvements, including reorganization and stronger phrasing, while preserving original intent. This goes beyond basic proofreading and polishing to enhance the overall quality and impact of the text. Consider restructuring sentences, paragraphs, or sections for better flow, replacing weak words with stronger alternatives, and improving clarity and consistency while maintaining the original meaning. However, avoid making changes just for the sake of change; every edit should serve a clear purpose in enhancing the text. \ No newline at end of file diff --git a/.github/prompts/polish.prompt.md b/.github/prompts/polish.prompt.md new file mode 100644 index 00000000000..276cd600d77 --- /dev/null +++ b/.github/prompts/polish.prompt.md @@ -0,0 +1,9 @@ +--- +description: Proofread and improve clarity without changing meaning or structure. +--- + +Follow the instructions in proofread.prompt.md. + +Then identify ways to further improve the clarity by making the document easier to read, scan, and understand, without moving paragraphs around, changing the meaning, or significantly increasing the length. This may include breaking up long sentences, adding subheadings, and improving word choice. Do not make changes just for the sake of change; every edit should serve a clear purpose in enhancing the text. + +Avoid changing any code samples directly, but flag any code issues or inconsistencies in the chat. \ No newline at end of file diff --git a/.github/prompts/proofread.prompt.md b/.github/prompts/proofread.prompt.md new file mode 100644 index 00000000000..b1f4347fd55 --- /dev/null +++ b/.github/prompts/proofread.prompt.md @@ -0,0 +1,10 @@ +--- +description: Check spelling, grammar, and basic style. +--- + +Proofread the document without altering meaning or structure: +* Check spelling, grammar, and basic style. + +Then further improve language and clarity without restructuring paragraphs or changing content order: +* Carefully go through each bullet point in the *Style standards* section of copilot-instructions.md and check if the guidance has been applied for each. +* Make sure that the front matter of the file adheres to the specified format and includes the required fields. \ No newline at end of file diff --git a/.github/prompts/review.prompt.md b/.github/prompts/review.prompt.md new file mode 100644 index 00000000000..ad49422b5ea --- /dev/null +++ b/.github/prompts/review.prompt.md @@ -0,0 +1,5 @@ +--- +description: Review the document and generate suggestions for improvement without any direct edits. +--- + +Analyze the page and return a list of suggestions or questions about any points to clarify, potential inconsistencies, and sections to restructure, add, or remove. Make no edits. \ No newline at end of file diff --git a/.github/release-notes-instructions.md b/.github/release-notes-instructions.md new file mode 100644 index 00000000000..004ba1a115b --- /dev/null +++ b/.github/release-notes-instructions.md @@ -0,0 +1,85 @@ +--- +applyTo: + - "content/en/docs/releasenotes/**/*.md" +--- + +# Release Notes Instructions + + + +## Essentials + +### Page Layout + +Use the existing template in `templates/release-notes-template.md` as a reference and ensure required fields are present and accurate. + +* Use `## {#anchor}` for each release, with a release date and optional download button. +* Allowed section headings: `New Features`, `Improvements`, `Fixes`, `Deprecations`, `Limitations`, `Breaking Changes`, `Known Issues`. +* Use `` before important fixes; cross-link with `[#123456](#123456)`. +* Add a `{{% button ... %}}` to Marketplace or download pages, if relevant. +* Use `{{% alert %}}` for critical notices. + +### Tone and Content + +* Accurate, factual, and concise; active voice. +* Include only customer-visible changes; omit internal notes. +* Include instructions or workarounds briefly, with links. +* Avoid marketing language; use images rarely. + +### Formatting Rules + +* New entries newest-first. +* Follow existing filename and styling patterns. +* Use a separate file per minor release unless grouping already exists. +* Prefix subsystem-specific notes (for example, "Improvements to SAP Deployment"). +* Append `(Ticket 123456)` where applicable; list ticketed items first, in ascending order. + +### Validation Workflow + +* Treat this as an edit-and-check workflow for existing release-note content. +* Validate structure first (front matter, heading levels, allowed section names), then normalize formatting and check for typos. +* Keep meaning unchanged unless explicitly asked to rewrite content. +* Don't add new claims, ticket IDs, or release details that are not already present. If something is missing, flag it in the chat. + +### Cross-References + +Use absolute paths for docs; use anchors or full URLs for other release notes. + +This guidance is a lightweight overlay over the main Copilot instructions. + +## Release Note Types + +Use the following table as an allowlist and quality reference when writing notes or checking existing notes. + +| Release Note Type | Definition | What Good Looks Like | Example | +| --- | --- | --- | --- | +| New Features | A major new feature that customers can see and use. | Name the feature and briefly describe it, including the user benefit. | We added a new feature that allows you to reverse an association direction by right-clicking the association and selecting **Reverse direction**. | +| Improvements | A functional fix or minor feature that makes behavior more consistent and predictable for customers. | State what changed and describe the user benefit of the new behavior. | Studio Pro now detects when an external date and time attribute that represents only a date has been localized and gives a consistency error. | +| Fixes | A technical bug or error fix, when reported by customers or when behavior or flow changed. | Preferred pattern starts with `We fixed an issue where...` and briefly describes where the bug occurred. If a customer reported it, include the ticket number. For Mendix-specific security vulnerabilities (CVEs), consult the Information Security team before publishing. | We fixed an issue where the bottom navigation bar invaded the Safe Area view on iPhone devices. (Ticket 187402) | +| Deprecations | Functionality that is no longer available, or that is deprecated and will be removed in a future version. | If removed, start with `We removed...` or `We dropped support for...`. If deprecated but not yet removed, start with `We deprecated...` and state when it will be removed. | We dropped support for PostgreSQL 11, as it is no longer supported by the vendor. | +| Known Issues | Confirmed unresolved issues that can affect users. May include workarounds. | Describe impact clearly and include workaround details when available. | For some activities in the logic editors, variable types are not visible or are shown as **Not set**. This is only a visual bug. (Tickets 205751, 207251) | +| Limitations | Known product constraints that are not necessarily defects. | State the limitation directly and explain scope. | This feature is available only for apps running in cloud-connected environments. | +| Breaking Changes | Confirmed changes that require user action or can break existing behavior. | State what changed, impact, and required user action. | We changed the default API endpoint format. Update existing integrations to use the new endpoint pattern before upgrading. | + +### Anchors and Ticket Links + +In the **Fixes** and **Known Issues** sections, include an HTML anchor for important tickets so readers can jump directly from other notes. Use the `` pattern immediately before the bullet item. Later, cross-link using `[#123456](#123456)` or by referencing the heading. + +### Alerts and Callouts + +Use the `{{% alert %}}` shortcode for important notices such as blog post links, upgrade warnings, or temporary workarounds. Example: + +```md +{{% alert color="info" %}} +For more information on this release, see the [Mendix 8.15 blog post](/blog/…). +{{% /alert %}} +``` + +### Cross-Referencing + +Always link to relevant documentation (refguide, how-to pages) using absolute paths. When referring to other release-note versions, use relative anchors or full URLs (for example, `/releasenotes/studio-pro/8.17/#875726`). Keep links descriptive and avoid vague text such as "see here." + +### Additional Notes + +* Keep text concise and technically focused; do not introduce marketing language. +* Refer to prior examples in the `releasenotes` tree when in doubt. \ No newline at end of file From 7c13e182f0872387a1e8a8f969671401ad1ae6ec Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Fri, 13 Mar 2026 17:18:40 +0100 Subject: [PATCH 2/3] Integrate feedback --- .github/copilot-instructions.md | 68 +++++++++++++-------------- .github/prompts/add.prompt.md | 2 +- .github/prompts/polish.prompt.md | 2 +- .github/release-notes-instructions.md | 2 +- 4 files changed, 36 insertions(+), 38 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 1715fdbe4c2..77c6fc66bda 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,11 +2,9 @@ -This repository contains the source for the Mendix documentation site, a Hugo-based static website that describes the Mendix low-code platform. Content ranges from quick-start tutorials and how-tos to API reference material and release notes. - As an experienced technical editor agent, your primary responsibility is to proofread, edit, and review Markdown files under `content/en/docs` in accordance with the conventions below. Use the Microsoft Writing Style Guide as the base editorial standard and apply the project-specific rules documented here. -## 0 Instruction precedence +## Instruction Precedence When instructions conflict, follow this order of precedence: @@ -14,23 +12,23 @@ When instructions conflict, follow this order of precedence: 2. Task-specific prompt files in `.github/prompts/*.prompt.md` when explicitly referenced. 3. Overlay instruction files (for example, `.github/release-notes-instructions.md`) when path-scoped. 4. This file (`.github/copilot-instructions.md`). -5. Existing conventions in nearby pages within the same section. +5. Existing conventions in nearby pages within the same folder. 6. Microsoft Writing Style Guide. -### 0.1 Default execution mode +### Default Execution Mode * MUST edit existing files in place unless the user explicitly asks to create new content. -* MUST preserve meaning, chronology, and intent. +* MUST preserve meaning and intent. * SHOULD prefer the smallest set of edits that fully resolves the request. -* MUST NOT add net-new product claims, technical behavior, ticket numbers, or release facts unless explicitly requested and sourced from provided content. +* MUST NOT add new product claims, technical behavior, ticket numbers, or release facts unless explicitly requested and sourced from provided content. -## 1. Project overview +## Project Overview -* **What** – Mendix is a low‑code application development platform that lets users visually design, build, test, and deploy web and mobile applications. -* **Who** – Target readers are developers, business analysts, and partners who consume the docs for learning, troubleshooting, and reference. -* **Tech stack** – Site built with [Hugo](https://gohugo.io/), custom theme and shortcodes under `layouts/`. Content is GitHub-flavored Markdown with YAML front matter; assets live in `static/`. +* **What** – This repository contains the source code for the Mendix documentation site, which describes the Mendix low‑code application development platform. Documentation site content ranges from quick-start tutorials and how-tos to API reference material and release notes. +* **Who** – Target readers are developers, business analysts, system administrators, and partners who consume the docs for learning, troubleshooting, and reference. Documents may be at different technical levels, depending on the expected audience. +* **Tech stack** – Hugo-based static website based on the Docsy theme. Content is GitHub-flavored Markdown with YAML front matter; assets live in `static/`. -## 2. Content structure and hierarchy +## Content Structure and Hierarchy The canonical tree is **`/content/en/docs`**. Top‑level directories correspond to major product areas (e.g. `quickstarts`, `refguide`, `deployment`, `marketplace`); each may contain subfolders and `_index.md` files that define section landing pages. @@ -51,11 +49,11 @@ content/en/docs/ ``` * **Index files (`_index.md`)** define landing pages or categories. They often use `cascade` to pass metadata to children and may set `type`, `layout`, `no_list`, `description_list` etc. -* Other `.md` files represent individual articles, how‑tos, reference topics, release notes, etc. File names should be simple, lowercase, and hyphen‑separated. +* Other `.md` files represent individual articles, how‑tos, reference topics, release notes, etc. File names must be simple, lowercase, and hyphen‑separated. Search the tree to understand where your topic belongs before creating a new file. -## 3. Style standards +## Style Standards * **Guiding manual** – Microsoft Writing Style Guide (https://learn.microsoft.com/style-guide/). Apply grammar, inclusive language, terminology, and formatting rules from that document. * **Tone** – Clear, concise, active voice; use imperative mood for procedures; second person (you/your) when addressing readers. Keep a conversational, straightforward tone. Present tense. Use American English and write for a global audience. Prefer short, everyday words; avoid or explain jargon. Keep it simple—short sentences and fragments are easier to scan and read, and prune excess words. Avoid marketing language. @@ -70,25 +68,26 @@ Search the tree to understand where your topic belongs before creating a new fil Project‑specific preferences are documented in the templates and in `community-tools` example pages; consult them for tricky formatting cases. -## 4. Technical implementation details +## Technical Implementation Details -### 4.1 Front matter +### Front Matter -All Markdown files begin with YAML metadata. Required fields vary by page type: +All Markdown files begin with YAML metadata. -* `title` – Human‑readable page title. -* `url` – Page URL. -* `description` – Summary used for metadata and search snippets. Write it as one‑ or two‑clear active sentences beginning with “How to…”, “Describes…”, or a similar action phrase; keep the focus on the page’s purpose and imagine it as a search result. -* `linktitle` – Optional; short text shown in the left navigation pane. -* `weight` – Optional; numeric ordering among siblings; use increments of 10 to leave room for future inserts. -* `draft` – Optional; set to `true` to exclude from production builds; remember to remove it before publishing. -* `numberless_headings` – Optional; set `true` for release notes and pages where heading numbering is unwanted. -* `cascade` – Optional; used only in `_index.md` files to propagate parameters (e.g. `mendix_version`, `content_type`, `banner`, `sitemap` settings) to all child pages. -* `type`, `layout`, `aliases` – Optional; rarely used for landing pages (see root `_index.md`). +* `title` – Human‑readable page title. (Required) +* `url` – Page URL. Start and end with `/`, use only lowercase letters, numbers, and hyphens. Doesn't need to match the file path. (Required) +* `description` – Summary used for metadata, search snippets, and content lists. Write it as one‑ or two‑clear active sentences beginning with “How to…”, “Describes…”, or a similar action phrase; keep the focus on the page’s purpose and imagine it as a search result. (Required) +* `linktitle` – Short text shown in the left navigation pane; use when `title` is longer than 40 characters. (Optional) +* `aliases` – Redirect paths for moved or renamed pages. Add old URLs as alias entries. (Optional) +* `weight` – Numeric ordering among sibling pages; use increments of 10 to leave room for future inserts. (Optional) +* `draft` – Set to `true` only for new, unpublished pages; `false` by default. (Optional) +* `cascade` – Used in `_index.md` files to propagate metadata to child pages. Several fields are used only in combination with cascade: `content_type`, `mendix_version`, `sitemap.priority`, and `old_content`. (Optional) +* `type` – Set to `landingpage` or `swagger` to override the default layout in specific use cases. (Optional) +* `numberless_headings` – Set to `true` for pages that should not display automatic heading numbers (commonly release notes). (Optional) -### 4.2 Shortcodes +### Shortcodes -Hugo shortcodes encapsulate reusable components. The ones you will encounter most frequently include: +Hugo shortcodes start with `{{` and encapsulate reusable components. The ones you will encounter most frequently include: * `figure` – Images and screenshots. Attributes: `src` (required), `alt` (required or `""`), `class`, `max-width`, `link`. Always store assets under `static/attachments/...` and reference with `/attachments/...`. @@ -96,7 +95,7 @@ Hugo shortcodes encapsulate reusable components. The ones you will encounter mos {{< figure src="/attachments/quickstarts/part1/3.login.png" alt="Sign in to Studio Pro" max-width="80%" >}} ``` -* `alert` – Callouts of type `info`, `warning`, `success`, or `danger`. +* `alert` – Callouts of type `info` and `warning`. ```md {{% alert color="warning" %}} This action cannot be undone. @@ -106,26 +105,25 @@ Hugo shortcodes encapsulate reusable components. The ones you will encounter mos * `button` – Link buttons with `color`, `href`, `text`, and optional `title` attributes. * `icon` – Inline SVG icons stored in `static/mx-icons` (`name` required, optional `color`) for use in UI descriptions. * `youtube` / `vidyard` – Embed videos by ID. -* `swaggerui` / `swaggerui-disable-try-it-out` – Render OpenAPI specs. +* `swaggerui` / `swaggerui-disable-try-it-out` – Render OpenAPI specs on pages with `type:swagger`. * `snippet` – Include external code or page content. * `tabpane` / `tab` – Create tabbed code examples. * `todo` – Internal draft notes; omitted in production. The `community-tools/contribute-to-mendix-docs/markdown-shortcodes.md` page contains comprehensive examples. Review it when adding new types or debugging rendering. -## 5. Editorial workflow +## Editorial Workflow 1. **Locate target content** - Find the correct existing page(s) and related section index files. 2. **Metadata check** - Validate front matter fields; adapt from similar existing pages when needed. 3. **Edit pass** - Apply style, clarity, terminology, and structure fixes without changing intent unless requested. -4. **Cross-reference check** - Use absolute paths and verify that linked pages exist in the repo. +4. **Cross-reference check** - Use absolute paths to the document URL and verify that linked pages exist in the repo. Don't use the path to the Markdown file. 5. **Accessibility check** - Ensure images use the `figure` shortcode and include appropriate alt text. 6. **Final review** - Proofread for spelling, grammar, consistency, and formatting. -7. **Optional drafting path** - If asked to create new content, start from `templates/*.md` and then follow the same checks above. -## 6. Standard content template +## Standard Content Template -Create new pages by copying one of the following templates and removing the comment lines (`#`): +If asked to create new content, start from `templates/*.md` and then follow the same checks above. Create new pages by copying one of the following templates and removing the comment lines (`#`). : * **How‑to** – `templates/how-to-template.md` * **Reference** – `templates/reference-template.md` diff --git a/.github/prompts/add.prompt.md b/.github/prompts/add.prompt.md index 2f14a2a80e6..900e317b853 100644 --- a/.github/prompts/add.prompt.md +++ b/.github/prompts/add.prompt.md @@ -2,6 +2,6 @@ description: Add new content to a page without rewriting existing content. --- -Prompt the user for the new content to add. Determine a suitable place to smoothly integrate the new content into the existing content, with appropriate transitions and formatting, while preserving the original meaning and structure of the page. Avoid making changes to existing content unless necessary for clarity or coherence when adding the new content. +Prompt the user for the new content to add. Determine a suitable place to smoothly integrate the new content into the existing content, with appropriate transitions and formatting, while preserving the original meaning and structure of the page. Don't make changes to existing content unless necessary for clarity or coherence when adding the new content. If the new content introduces redundancy or conflicts with existing content, flag these issues in the chat and suggest ways to resolve them without directly editing the existing content. \ No newline at end of file diff --git a/.github/prompts/polish.prompt.md b/.github/prompts/polish.prompt.md index 276cd600d77..4b88b3783d8 100644 --- a/.github/prompts/polish.prompt.md +++ b/.github/prompts/polish.prompt.md @@ -6,4 +6,4 @@ Follow the instructions in proofread.prompt.md. Then identify ways to further improve the clarity by making the document easier to read, scan, and understand, without moving paragraphs around, changing the meaning, or significantly increasing the length. This may include breaking up long sentences, adding subheadings, and improving word choice. Do not make changes just for the sake of change; every edit should serve a clear purpose in enhancing the text. -Avoid changing any code samples directly, but flag any code issues or inconsistencies in the chat. \ No newline at end of file +Do not change any code samples directly, but flag any code issues or inconsistencies in the chat. \ No newline at end of file diff --git a/.github/release-notes-instructions.md b/.github/release-notes-instructions.md index 004ba1a115b..0e090de3252 100644 --- a/.github/release-notes-instructions.md +++ b/.github/release-notes-instructions.md @@ -13,7 +13,7 @@ applyTo: Use the existing template in `templates/release-notes-template.md` as a reference and ensure required fields are present and accurate. -* Use `## {#anchor}` for each release, with a release date and optional download button. +* For Studio Pro release notes, use `## {#anchor}` for each release, with a release date and optional download button. * Allowed section headings: `New Features`, `Improvements`, `Fixes`, `Deprecations`, `Limitations`, `Breaking Changes`, `Known Issues`. * Use `` before important fixes; cross-link with `[#123456](#123456)`. * Add a `{{% button ... %}}` to Marketplace or download pages, if relevant. From 212bc420a41ae782262bc15467fbc84629ef99eb Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Fri, 13 Mar 2026 17:27:25 +0100 Subject: [PATCH 3/3] Remove RN instructions page --- .github/release-notes-instructions.md | 85 --------------------------- 1 file changed, 85 deletions(-) delete mode 100644 .github/release-notes-instructions.md diff --git a/.github/release-notes-instructions.md b/.github/release-notes-instructions.md deleted file mode 100644 index 0e090de3252..00000000000 --- a/.github/release-notes-instructions.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -applyTo: - - "content/en/docs/releasenotes/**/*.md" ---- - -# Release Notes Instructions - - - -## Essentials - -### Page Layout - -Use the existing template in `templates/release-notes-template.md` as a reference and ensure required fields are present and accurate. - -* For Studio Pro release notes, use `## {#anchor}` for each release, with a release date and optional download button. -* Allowed section headings: `New Features`, `Improvements`, `Fixes`, `Deprecations`, `Limitations`, `Breaking Changes`, `Known Issues`. -* Use `` before important fixes; cross-link with `[#123456](#123456)`. -* Add a `{{% button ... %}}` to Marketplace or download pages, if relevant. -* Use `{{% alert %}}` for critical notices. - -### Tone and Content - -* Accurate, factual, and concise; active voice. -* Include only customer-visible changes; omit internal notes. -* Include instructions or workarounds briefly, with links. -* Avoid marketing language; use images rarely. - -### Formatting Rules - -* New entries newest-first. -* Follow existing filename and styling patterns. -* Use a separate file per minor release unless grouping already exists. -* Prefix subsystem-specific notes (for example, "Improvements to SAP Deployment"). -* Append `(Ticket 123456)` where applicable; list ticketed items first, in ascending order. - -### Validation Workflow - -* Treat this as an edit-and-check workflow for existing release-note content. -* Validate structure first (front matter, heading levels, allowed section names), then normalize formatting and check for typos. -* Keep meaning unchanged unless explicitly asked to rewrite content. -* Don't add new claims, ticket IDs, or release details that are not already present. If something is missing, flag it in the chat. - -### Cross-References - -Use absolute paths for docs; use anchors or full URLs for other release notes. - -This guidance is a lightweight overlay over the main Copilot instructions. - -## Release Note Types - -Use the following table as an allowlist and quality reference when writing notes or checking existing notes. - -| Release Note Type | Definition | What Good Looks Like | Example | -| --- | --- | --- | --- | -| New Features | A major new feature that customers can see and use. | Name the feature and briefly describe it, including the user benefit. | We added a new feature that allows you to reverse an association direction by right-clicking the association and selecting **Reverse direction**. | -| Improvements | A functional fix or minor feature that makes behavior more consistent and predictable for customers. | State what changed and describe the user benefit of the new behavior. | Studio Pro now detects when an external date and time attribute that represents only a date has been localized and gives a consistency error. | -| Fixes | A technical bug or error fix, when reported by customers or when behavior or flow changed. | Preferred pattern starts with `We fixed an issue where...` and briefly describes where the bug occurred. If a customer reported it, include the ticket number. For Mendix-specific security vulnerabilities (CVEs), consult the Information Security team before publishing. | We fixed an issue where the bottom navigation bar invaded the Safe Area view on iPhone devices. (Ticket 187402) | -| Deprecations | Functionality that is no longer available, or that is deprecated and will be removed in a future version. | If removed, start with `We removed...` or `We dropped support for...`. If deprecated but not yet removed, start with `We deprecated...` and state when it will be removed. | We dropped support for PostgreSQL 11, as it is no longer supported by the vendor. | -| Known Issues | Confirmed unresolved issues that can affect users. May include workarounds. | Describe impact clearly and include workaround details when available. | For some activities in the logic editors, variable types are not visible or are shown as **Not set**. This is only a visual bug. (Tickets 205751, 207251) | -| Limitations | Known product constraints that are not necessarily defects. | State the limitation directly and explain scope. | This feature is available only for apps running in cloud-connected environments. | -| Breaking Changes | Confirmed changes that require user action or can break existing behavior. | State what changed, impact, and required user action. | We changed the default API endpoint format. Update existing integrations to use the new endpoint pattern before upgrading. | - -### Anchors and Ticket Links - -In the **Fixes** and **Known Issues** sections, include an HTML anchor for important tickets so readers can jump directly from other notes. Use the `` pattern immediately before the bullet item. Later, cross-link using `[#123456](#123456)` or by referencing the heading. - -### Alerts and Callouts - -Use the `{{% alert %}}` shortcode for important notices such as blog post links, upgrade warnings, or temporary workarounds. Example: - -```md -{{% alert color="info" %}} -For more information on this release, see the [Mendix 8.15 blog post](/blog/…). -{{% /alert %}} -``` - -### Cross-Referencing - -Always link to relevant documentation (refguide, how-to pages) using absolute paths. When referring to other release-note versions, use relative anchors or full URLs (for example, `/releasenotes/studio-pro/8.17/#875726`). Keep links descriptive and avoid vague text such as "see here." - -### Additional Notes - -* Keep text concise and technically focused; do not introduce marketing language. -* Refer to prior examples in the `releasenotes` tree when in doubt. \ No newline at end of file