diff --git a/.github/skills/update-docs/SKILL.md b/.github/skills/update-docs/SKILL.md new file mode 100644 index 0000000000..5ea4ea3fdc --- /dev/null +++ b/.github/skills/update-docs/SKILL.md @@ -0,0 +1,61 @@ +--- +name: update-docs +description: > + Update user or developer documentation only if the change is relevant to the specific purpose of the documentation. + Use when editing files within the `docs/` folder. +--- + +# Updating Documentation + +You are a pragmatic senior developer who is particular about maintaining concise but useful & relevant documentation. +Follow this workflow to ensure documentation updates are relevant and purposeful. + +## 1. Determine Documentation Purpose +Identify the **goal** of the documentation you are updating: +- **User Documentation**: Focuses on how to use the project (features, APIs, workflows, examples). +- **Developer Documentation**: Focuses on how to contribute to the project (architecture, internals, build processes, dependencies). + +## 2. Assess Change Relevance +For each change, evaluate its relevance based on the documentation type: + +| Change Type | User Documentation | Developer Documentation | +|---------------------------|----------------------------------------|----------------------------| +| New feature | ✅ Update (usage, examples) | ✅ Update (implementation) | +| Breaking change | ✅ Update (migration notes) | ✅ Update (code changes) | +| Bug fix | ✅ Update if user-facing | ✅ Update if relevant | +| Dependency bump | ❌ Skip | ❌ Skip | +| Internal refactor | ❌ Skip | ✅ Only if affects workflow | + +## 3. Review Changes +Use ONLY the following to obtain the changelog: +```bash +bash /mnt/skills/user/update-docs/scripts/get-diff.sh [arg1] +``` +Arguments: +- `arg1` - Optional argument that should be used when a specific SHA is specifically supplied. + +Output: +The git diff and relevant changes to review. + +## 4. Key Questions for LLM pre-review +Before updating, ask: +- *"Does this change directly impact the audience (users or developers) of the documentation I’m editing? If not, skip it."* +- *"Am I unsure of any part of the update I'm making? If so, I must clarify before proceeding."* + +## 4. Update Documentation +- **User Documentation**: Focus on what users need to know (e.g., new features, deprecated functionality). +- **Developer Documentation**: Focus on what developers need to know (e.g., new build steps, architecture changes). + +When updating documentation, keep in mind the rules specified in [RULES.md](docs/RULES.md) + +## 5. Diagrams and Visuals +- Add/update **Mermaid diagrams** if the change affects workflows, architecture, or user/developer processes. +- For static diagrams (e.g., `.png`), flag for manual review if the change alters the visualized concept. + +## 6. Rules for Packages/Dependencies +- **User Documentation**: Only mention packages if they are part of the public interface (e.g., "This project requires Docker 20.10+"). +- **Developer Documentation**: List packages only if they are critical to the build/development process (e.g., "Use Node.js 18+"). + +## 7. Automation Tips +- Pre-filter changes using scripts (e.g., ignore `package.json` updates unless they include `BREAKING CHANGE` or `feat`). +- Flag ambiguous cases for manual review (e.g., "This change might affect the 'Configuration' section—please verify"). diff --git a/.github/skills/update-docs/docs/RULES.md b/.github/skills/update-docs/docs/RULES.md new file mode 100644 index 0000000000..1efb2de009 --- /dev/null +++ b/.github/skills/update-docs/docs/RULES.md @@ -0,0 +1,357 @@ +# MarkBind Documentation Rules and Best Practices + +## Basic Rules + +### 1. Frontmatter Usage +All documentation files must start with a frontmatter section containing at least a title. + +```markdown + + title: "Page Title" + +``` + +Some files may include additional metadata like layout, pageNav, etc. + +### 2. Lead Placement +Lead text (introductory text) should only appear at the top of pages, typically right after the main heading. + +```markdown +

**Main Title**

+ +Introductory lead text goes here. +``` + +### 3. Environment Tags +Use environment tags to control content visibility across different documentation environments: + +- `environment--ug` for User Guide content +- `environment--dg` for Developer Guide content +- `environment--combined` for both environments + +```markdown +
+ +
+ +
+ +
+``` + +### 4. MarkBind Text Formatting Syntax + +#### Highlighted Text +```markdown +==highlighted text== +``` + +#### Grey/Dimmed Text +```markdown +%%grey text%% +``` + +#### Underlined Text +```markdown +!!underlined text!! +``` + +#### Strikethrough Text +```markdown +~~strikethrough text~~ +``` + +#### Bold and Italic +```markdown +**bold text** +_italic text_ +___bold and italic___ +``` + +### 5. Tooltips +Use tooltips for inline explanations and definitions: + +```markdown +trigger text +``` + +Examples: +```markdown +CS +nvm +_more dynamic_ +``` + +Tooltip placement options: +```markdown +trigger +``` + +### 6. Popovers and Modals +Use triggers with popovers and modals for interactive content: + +```markdown +trigger text + +
+ Popover content here +
+
+ +trigger text + + Modal content here + +``` + +### 7. Content Reuse with Includes +Use the include mechanism to avoid duplication and maintain consistency: + +```markdown + + value + +``` + +## Consistent Formatting Rules + +### 1. Text Styles +Maintain consistent use of MarkBind text formatting throughout documentation: + +- `**bold**` and `_italic_` for emphasis +- `==highlighted text==` for important concepts +- `%%dimmed text%%` for secondary information +- `!!underlined text!!` for interactive elements +- `~~strikethrough~~` for deprecated or removed content + +### 2. Code Examples +Use consistent code formatting with proper syntax highlighting: + +```markdown +```html +trigger +``` + +For code and output examples: +```markdown + + markdown + + Example code here + + +``` + +### 3. Panels and Boxes +Organize content using panels and boxes: + +```markdown + + Panel content here + + + + Grouped content here + +``` + +Panel types: +- `seamless` - no border, blends with page +- `primary`, `secondary`, `success`, `danger`, `warning`, `info` - colored panels +- Custom headers with `%%text%%` formatting + +### 4. Lists and Tables +Use proper Markdown formatting for lists and tables: + +```markdown +- List item 1 +- List item 2 + - Nested item + +1. Numbered item 1 +2. Numbered item 2 + +Syntax | Code | Output +-------|------|------- +Markdown | `**bold**` | **bold** +``` + +### 5. Cross-referencing +Link to other documentation sections using relative paths: + +```markdown +[link text](userGuide/formattingContents.html) +[link text](userGuide/formattingContents.html#section-id) +``` + +### 6. Environment-Specific Content +Wrap environment-specific content appropriately: + +```markdown +
+ +
+ +
+ +
+``` + +## Best Practices + +### 1. Interactive Elements +Use tooltips, popovers, and modals judiciously: +- Tooltips for brief explanations and definitions +- Popovers for slightly more detailed information +- Modals for complex or lengthy content that shouldn't interrupt main flow + +### 2. Content Organization +Use panels, boxes, and tabs to organize related content logically: + +```markdown + + + Content for tab 1 + + + Content for tab 2 + + +``` + +### 3. Version Information +Include version-specific details, especially for installation and update instructions: + +```markdown +[Node.js](https://nodejs.org) {{ node_version }} or higher installed +``` + +### 4. Prerequisites +Clearly list prerequisites at the beginning of guides: + +```markdown +++**Prerequisites**++ + +
+ %%{{ icon_ticked }}%% Requirement 1 + %%{{ icon_ticked }}%% Requirement 2 +
+``` + +### 5. Step-by-Step Instructions +Provide clear, numbered steps with appropriate code examples: + +```markdown +++**1. Step Title**++ + +Instruction text here + +``` +code example here +``` + +++**2. Next Step**++ + +More instructions +``` + +### 6. Contributor Sections +Maintain the ALL-CONTRIBUTORS-LIST format without modification: + +```markdown + + + + + +
+ + + +``` + +### 7. 404 Page Format +Use the specific arrow syntax for 404 pages: + +```markdown +->

404

<- +->

File not found
Click here to go back to the home page.

<- +``` + +### 8. Icons and Emoji +Use consistent icon and emoji formatting: + +```markdown +:glyphicon-icon-name: +:fa-solid-icon-name: +:fa-brands-icon-name: +:emoji-shortcode: +``` + +### 9. Variables and Templates +Use variables for consistent values across documentation: + +```markdown +{% set title = "Page Title" %} +{{ title }} +``` + +### 10. Comments and Annotations +Use proper comment formatting: + +```markdown + + +{% comment %} +Multi-line +comment block +{% endcomment %} + +%%Comment that appears in output%% +``` + +## File Structure and Organization + +### Frontmatter Requirements +- All `.md` files should have frontmatter with at least `title` +- User guide files should include `layout: userGuide.md` +- Developer guide files should include `layout: devGuide.md` + +### Directory Structure +- `docs/` - Main documentation root +- `docs/userGuide/` - User guide content +- `docs/devGuide/` - Developer guide content +- `docs/_markbind/` - Templates and boilerplates +- `docs/pages/` - Reusable content fragments + +### Configuration Files +- `site.json` - Main site configuration +- `ug-site.json` - User guide specific configuration +- `dg-site.json` - Developer guide specific configuration + +## Writing Style Guidelines + +1. **Concise Language**: Use clear, direct language suitable for an LLM audience +2. **Consistent Terminology**: Use established MarkBind terminology consistently +3. **Logical Flow**: Organize content from basic to advanced concepts +4. **Practical Examples**: Include relevant examples for each concept +5. **Cross-references**: Link to related documentation sections +6. **Version Awareness**: Note version-specific behaviors and requirements +7. **Timelessness and clarity**: Avoid using phrasies like "now supports". Communicate about the product in the current state and be clear. + +## Navigation Rules + +### Previous/Next Configuration + +When adding or modifying navigation links in the documentation, ensure that the `previous_next` configuration is updated to maintain proper navigation flow. Specifically: + +- The "previous" link of the page that comes after the new page should point to the new page. +- The "next" link of the page that comes before the new page should point to the new page. + +This ensures that users can navigate through the documentation seamlessly without encountering broken links or incorrect navigation paths. + +**Example**: +```markdown +{% from "njk/common.njk" import previous_next %} +{{ previous_next('previousPage', 'nextPage') }} +``` diff --git a/.github/skills/update-docs/scripts/get-diff.sh b/.github/skills/update-docs/scripts/get-diff.sh new file mode 100644 index 0000000000..edd6f82299 --- /dev/null +++ b/.github/skills/update-docs/scripts/get-diff.sh @@ -0,0 +1,15 @@ +#!/bin/bash + +# Git diff script that supports optional base commit SHA parameter +# Usage: ./get-diff.sh [COMMIT_SHA] + +# Check if a commit SHA parameter is provided +if [ $# -eq 1 ]; then + # Use the provided commit SHA + echo "Showing diff from commit: $1" + git diff "$1" +else + # Use the default: diff from fork point with master + echo "Showing diff from fork point with master" + git diff $(git merge-base --fork-point master) +fi diff --git a/docs/_markbind/layouts/devGuide.md b/docs/_markbind/layouts/devGuide.md index 64e9e4cbb2..c826049108 100644 --- a/docs/_markbind/layouts/devGuide.md +++ b/docs/_markbind/layouts/devGuide.md @@ -17,6 +17,7 @@ * Development :expanded: * [Setting up]({{baseUrl}}/devGuide/development/settingUp.html) * [Workflow]({{baseUrl}}/devGuide/development/workflow.html) + * [Skills]({{baseUrl}}/devGuide/development/skills.html) * [Writing Components]({{baseUrl}}/devGuide/development/writingComponents.html) * [Writing Plugins]({{baseUrl}}/devGuide/development/writingPlugins.html) * [Migrating to TypeScript]({{baseUrl}}/devGuide/development/migratingToTypeScript.html) diff --git a/docs/devGuide/development/skills.md b/docs/devGuide/development/skills.md new file mode 100644 index 0000000000..06080d4ef4 --- /dev/null +++ b/docs/devGuide/development/skills.md @@ -0,0 +1,51 @@ +{% set title = "Skills" %} +{{ title }} + + + title: "{{ title }}" + layout: devGuide.md + pageNav: default + + +# {{ title }} + +
+ +Skills are directories containing instructions, scripts, and resources that AI agents dynamically load to handle specific tasks. Each skill has a `SKILL.md` file that defines when it should be activated and what instructions the AI agent should follow. +
+ +## Overview + +Skills are designed to improve AI agent performance by providing structured instructions and resources for specific tasks. This is applicable to any AI agent with skill support, and developers can point AI agents to the skills directory for structured task handling. + +## Skills Directory + +Skills are located in the `.github/skills/` directory. You can point AI agents to this directory to leverage the structured instructions and resources provided by the skills. + +## List of Skills + +The following skills are available in the MarkBind project: + +| Skill Name | Description | +|------------|-------------| +| `update-docs` | Update user or developer documentation only if the change is relevant to the specific purpose of the documentation. Use when editing files within the `docs/` folder. | + +## Adding New Skills + +If you find yourself performing similar structured tasks with an AI agent, consider adding a new skill to the `.github/skills/` directory. Each skill should include: + +1. A `SKILL.md` file that defines the skill's purpose, when it should be activated, and what instructions the AI agent should follow. +2. Any necessary scripts or resources to support the skill's functionality. +3. Clear documentation on how to use the skill. + +## Using Skills + +Skills relevant to particular tasks should be invoked automatically by AI agents. You may opt to directly point the agent to a skill. + +## Useful Links +- [Skill.sh skill repository](https://skills.sh/) +- [Cline reference on skills & writing them](https://docs.cline.bot/features/skills) +- [Claude reference on skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) + +{% from "njk/common.njk" import previous_next %} +{{ previous_next('workflow', 'writingComponents') }} diff --git a/docs/devGuide/development/workflow.md b/docs/devGuide/development/workflow.md index 705028b724..fedaff7554 100644 --- a/docs/devGuide/development/workflow.md +++ b/docs/devGuide/development/workflow.md @@ -419,5 +419,12 @@ To update PlantUML to a newer version: As Bootswatch is built on Bootstrap, ensure that the versions of both are in sync to avoid unexpected differences in styling behavior between default and other themes. Both are currently using version 5.1.3. +## Using Skills +As a developer, you may use AI in your workflow to perform tasks. If a specific task is done repeatedly, you may leverage Skills to improve AI output and save time. + +Skills are invoked whenever an agent detects a task to be relevant to one, though sometimes manual pointing may be necessary. + +MarkBind houses several skills that you may find useful. See the [Skills](./skills.md) page for a full list and more information. + {% from "njk/common.njk" import previous_next %} -{{ previous_next('settingUp', 'writingComponents') }} +{{ previous_next('settingUp', 'skills') }} diff --git a/docs/devGuide/development/writingComponents.md b/docs/devGuide/development/writingComponents.md index b2ba4469f8..32d64652fe 100644 --- a/docs/devGuide/development/writingComponents.md +++ b/docs/devGuide/development/writingComponents.md @@ -153,4 +153,4 @@ MarkBind should also **log a warning** to inform the author of this conflict! {% from "njk/common.njk" import previous_next %} -{{ previous_next('workflow', 'writingPlugins') }} \ No newline at end of file +{{ previous_next('skills', 'writingPlugins') }}