Skip to content

chore: sync markdown instructions to radius and ai-extensions #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
brooke-hamilton wants to merge 1 commit into
base: main
Choose a base branch
from
+38 −0
Open

chore: sync markdown instructions to radius and ai-extensions #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
7 changes: 7 additions & 0 deletions .github/sync.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,13 @@ group:
- source: sync-templates/.github/instructions/shell.instructions.md
dest: .github/instructions/shell.instructions.md

- repos: |
radius-project/radius
radius-project/ai-extensions
files:
- source: sync-templates/.github/instructions/markdown.instructions.md
dest: .github/instructions/markdown.instructions.md

# Spellcheck (cspell) config and workflow for the documentation-heavy repos.
# Destination workflow keeps the existing `.yaml` extension so it overwrites
# the per-repo workflow instead of creating a duplicate.
Expand Down
31 changes: 31 additions & 0 deletions sync-templates/.github/instructions/markdown.instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
---
description: 'Conventions for authoring Markdown in this repository'
applyTo: '**/*.md'
---

<!--
This file is synced from the radius-project/.github repository.
DO NOT EDIT MANUALLY - changes will be overwritten by the next sync.
Source: https://github.com/radius-project/.github
-->

# Markdown Guidelines

Formatting rules for Markdown are enforced by tooling. This file covers only the conventions the linters cannot check and points to the source of truth for everything else.

## Source of truth

Do not restate or duplicate lint rules here — change the configuration instead, otherwise this file will drift from what is actually enforced.

- **Rules:** `markdownlint-cli2`, configured by [`.github/linters/.markdownlint-cli2.yaml`](../linters/.markdownlint-cli2.yaml), which extends [`.github/linters/.markdownlint.yml`](../linters/.markdownlint.yml).
- **Tables:** formatted by `markdown-table-formatter`.

Both tools are installed as dev dependencies in the root `package.json`. See the `radius-markdown-lint` skill for how to run them.

## Conventions not enforced by tooling

- **Do not hard-wrap prose.** Write each paragraph as a single long line. The line-length rule (MD013) is intentionally disabled; manual line breaks create noisy diffs and break reflowing in editors. This applies to all prose — paragraphs, list item text, blockquote content, and image/link alt text. Code blocks and tables are excluded.

## Before committing

Run the Markdown linters (see the `radius-markdown-lint` skill) on the files you changed and fix any reported issues.