Merge pull request #6049 from continuedev/bdougie/markdown-first-rules

docs: markdown first rules

Author: tomasz-stefaniak

docs/docs/agent/how-to-customize.md

@@ -9,7 +9,7 @@ sidebar_position: 5
 
 Adding Rules can be done in your assistant locally or in the Hub.
 
-[Explore Rules on the Hub](https://hub.continue.dev/explore/rules) and see the [Rules deep dive](../customize/deep-dives/rules.md) for more details and tips on creating rules.
+[Explore Rules on the Hub](https://hub.continue.dev/explore/rules) and see the [Rules deep dive](../customize/deep-dives/rules.mdx) for more details and tips on creating rules.
 
 ## Add MCP tools
 

docs/docs/blocks/rules.md

@@ -22,4 +22,4 @@ Your assistant detects rule blocks and applies the specified rules while in [Age
 
 ## Learn More
 
-Learn more in the [rules deep dive](../customize/deep-dives/rules.md), and view [`rules`](../reference.md#rules) in the YAML Reference for more details.
+Learn more in the [rules deep dive](../customize/deep-dives/rules.mdx), and view [`rules`](../reference.md#rules) in the YAML Reference for more details.

docs/docs/chat/how-to-customize.md

@@ -7,7 +7,7 @@ sidebar_position: 5
 
 There are a number of different ways to customize Chat:
 
-- You can add a [`rules` block](../hub/blocks/block-types.md#rules) to your assistant to give the model persistent instructions through the system prompt. See the [rules deep dive](../customize/deep-dives/rules.md) for more information.
+- You can add a [`rules` block](../hub/blocks/block-types.md#rules) to your assistant to give the model persistent instructions through the system prompt. See the [rules deep dive](../customize/deep-dives/rules.mdx) for more information.
 - You can configure [`@Codebase`](../customize/deep-dives/codebase.mdx)
 - You can configure [`@Docs`](../customize/deep-dives/docs.mdx)
 - You can [build your own context provider](../customize/tutorials/build-your-own-context-provider.mdx)

docs/docs/customize/deep-dives/rules.md renamed to docs/docs/customize/deep-dives/rules.mdx

@@ -3,6 +3,9 @@ description: Rules are used to provide instructions to the model for Chat, Edit,
 keywords: [rules, .continuerules, system, prompt, message]
 ---
 
+import TabItem from "@theme/TabItem";
+import Tabs from "@theme/Tabs";
+
 # Rules
 
 Rules provide instructions to the model for [Chat](../../chat/how-to-use-it.md), [Edit](../../edit/how-to-use-it.md), and [Agent](../../agent/how-to-use-it.md) requests.
@@ -23,15 +26,15 @@ To form the system message, rules are joined with new lines, in the order they a
 Below is a quick example of setting up a new rule file:
 
 1. Create a folder called `.continue/rules` at the top level of your workspace
-2. Add a file called `pirates-rule.yaml` to this folder.
-3. Write the following contents to `pirates-rule.prompt` and save.
+2. Add a file called `pirates-rule.md` to this folder.
+3. Write the following contents to `pirates-rule.md` and save.
 
-```yaml title=".continue/rules/pirates-rule.yaml"
+```md title=".continue/rules/pirates-rule.md"
+---
 name: Pirate rule
-version: 0.0.1
-schema: v1
-rules:
-  - Talk like a pirate.
+---
+
+- Talk like a pirate.
 ```
 
 Now test your rules by asking a question about a file in chat.
@@ -58,68 +61,101 @@ Explore available rules [here](https://hub.continue.dev/explore/rules), or [crea
 
 Rules blocks can be simple text, written in YAML configuration files, or as Markdown (`.md`) files. They can have the following properties:
 
-- `name` (**required**): A display name/title for the rule
-- `rule` (**required**): The text content of the rule
-- `schema` (**required**): The schema version of the YAML file (e.g., `v1`)
+- `name` (**required** for YAML): A display name/title for the rule
 - `globs` (optional): When files are provided as context that match this glob pattern, the rule will be included. This can be either a single pattern (e.g., `"**/*.{ts,tsx}"`) or an array of patterns (e.g., `["src/**/*.ts", "tests/**/*.ts"]`).
-
-```yaml title=".config.yaml"
-rules:
-  - Always annotate Python functions with their parameter and return types
-
-  - name: TypeScript best practices
-    rule: Always use TypeScript interfaces to define shape of objects. Use type aliases sparingly.
-    globs: "**/*.{ts,tsx}"
-
-  - name: TypeScript test patterns
-    rule: In TypeScript tests, use Jest's describe/it pattern and follow best practices for mocking.
-    globs:
-      - "src/**/*.test.ts"
-      - "tests/**/*.ts"
-
-  - uses: myprofile/my-mood-setter
-    with:
-      TONE: concise
-```
+- `alwaysApply`: true - Always include the rule, regardless of file context
+- `alwaysApply`: false - Only include if globs exist AND match file context
+- `alwaysApply`: undefined - Default behavior: include if no globs exist OR globs exist and match
+
+<Tabs groupId="rules-example">
+  <TabItem value="md" label="Markdown">
+  ```yaml title="doc-standards.md"
+  ---
+  name: Documentation Standards
+  globs: docs/**/*.{md,mdx}
+  alwaysApply: false
+  description: Standards for writing and maintaining Continue Docs
+  ---
+
+# Continue Docs Standards
+
+- Follow Docusaurus documentation standards
+- Include YAML frontmatter with title, description, and keywords
+- Use consistent heading hierarchy starting with h2 (##)
+- Include relevant Admonition components for tips, warnings, and info
+- Use descriptive alt text for images
+- Include cross-references to related documentation
+- Reference other docs with relative paths
+- Keep paragraphs concise and scannable
+- Use code blocks with appropriate language tags
+
+  ````
+  </TabItem>
+  <TabItem value="yaml" label="YAML">
+
+  ```yaml title="doc-standards.yaml"
+  name: Documentation Standards
+  globs: docs/**/*.{md,mdx}
+  alwaysApply: false
+  rules:
+    - name: Documentation Standards
+      rule: >
+        - Follow Docusaurus documentation standards
+        - Include YAML frontmatter with title, description, and keywords
+        - Use consistent heading hierarchy starting with h2 (##)
+        - Include relevant Admonition components for tips, warnings, and info
+        - Use descriptive alt text for images
+        - Include cross-references to related documentation
+        - Reference other docs with relative paths
+        - Keep paragraphs concise and scannable
+        - Use code blocks with appropriate language tags
+  ````
+
+      </TabItem>
+
+  </Tabs>
 
 ### `.continue/rules` folder
 
 You can create project-specific rules by adding a `.continue/rules` folder to the root of your project and adding new rule files.
 
-```yaml title=".continue/rules/new-rule.yaml"
+```md title=".continue/rules/new-rule.md"
+---
 name: New rule
-version: 0.0.1
-schema: v1
-rules:
-  - Always give concise responses
+---
+
+Always give concise responses
 ```
 
-This is also done when selecting "Add Rule" in the Assistant settings. This will create a new folder in `.continue/rules` with a default file named `new-rule.yaml`.
+This is also done when selecting "Add Rule" in the Assistant settings. This will create a new folder in `.continue/rules` with a default file named `new-rule.md`.
 
 ### Examples
 
 If you want concise answers:
 
-```yaml title=".continue/rules/concise-rule.yaml"
-rules:
-  - name: Always give concise answers
-    rule: |
-      Please provide concise answers. Don't explain obvious concepts. 
-      You can assume that I am knowledgable about most programming topics.
+```md title=".continue/rules/concise-rule.md"
+---
+name: Always give concise answers
+---
+
+Please provide concise answers. Don't explain obvious concepts.
+You can assume that I am knowledgable about most programming topics.
 ```
 
 If you want to ensure certain practices are followed, for example in React:
 
-```yaml title=".continue/rules/functional-rule.yaml"
-rules:
-  - name: Always use functional components
-    rule: |
-      Whenever you are writing React code, make sure to
-      - use functional components instead of class components
-      - use hooks for state management
-      - define an interface for your component props
-      - use Tailwind CSS for styling
-      - modularize components into smaller, reusable pieces
+```md title=".continue/rules/functional-rule.md"
+---
+name: Always use functional components
+---
+
+Whenever you are writing React code, make sure to
+
+- use functional components instead of class components
+- use hooks for state management
+- define an interface for your component props
+- use Tailwind CSS for styling
+- modularize components into smaller, reusable pieces
 ```
 
 ### Chat System Message

docs/docs/hub/blocks/block-types.md

@@ -35,7 +35,7 @@ Learn more in the [MCP deep dive](../../customize/deep-dives/mcp.mdx), and view
 
 Rules blocks are instructions that your custom AI code assistant will always keep in mind - the contents of rules are inserted into the system message for all Chat requests. [Explore rules](https://hub.continue.dev/explore/rules) on the hub.
 
-Learn more in the [rules deep dive](../../customize/deep-dives/rules.md), and view [`rules`](../../reference.md#rules) in the YAML Reference for more details.
+Learn more in the [rules deep dive](../../customize/deep-dives/rules.mdx), and view [`rules`](../../reference.md#rules) in the YAML Reference for more details.
 
 ## Prompts
 

docs/docs/reference.md

@@ -296,7 +296,7 @@ context:
 
 List of rules that the LLM should follow. These are concatenated into the system message for
 all [Chat](./chat/how-to-use-it.md), [Edit](./edit/how-to-use-it.md), and [Agent](./agent/how-to-use-it.md) requests.
-See the [rules deep dive](./customize/deep-dives/rules.md) for details.
+See the [rules deep dive](./customize/deep-dives/rules.mdx) for details.
 
 Explicit rules can either be simple text or an object with the following properties: