Professional markdown writing standards for documentation and content creation
This skill auto-activates when working on markdown files and provides comprehensive guidelines for creating professional, accessible, and well-structured documentation.
Enforce documentation and content creation standards for all markdown files in the project.
#) - H1 is auto-generated from the document title##) for main sections - Primary organizational level###) for subsections - Secondary organizational levelExample:
## Main Section (H2)
### Subsection (H3)
Content here...
### Another Subsection (H3)
More content...
## Another Main Section (H2)
- for bullet points - Consistent bullet style1. for numbered lists - Auto-incrementing numbersExample:
Main list:
- First item
- Second item
- Nested item
- Another nested item
- Third item
Numbered list:
1. First step
2. Second step
3. Third step
Example:
Use inline code like `const foo = 'bar'` for short snippets.
For code blocks:
\`\`\`typescript
function greet(name: string): string {
return `Hello, ${name}!`;
}
\`\`\`
[text](URL)[text](URL "tooltip")Example:
✅ Good: Read the [TypeScript documentation](https://www.typescriptlang.org/docs/)
❌ Bad: Click [here](https://www.typescriptlang.org/docs/)
With tooltip: [TypeScript docs](https://www.typescriptlang.org/docs/ "Official TypeScript documentation")
Example:
--- separatorExample:
| Feature | Status | Priority |
|---------|:------:|----------|
| Authentication | ✅ Complete | High |
| User Profile | 🚧 In Progress | Medium |
| Notifications | ⏳ Planned | Low |
Example:
This is a long paragraph that should be broken at approximately 80 characters
per line. This makes it easier to read diffs and maintains good version control
practices. Each sentence or major clause can start on a new line.
Example:
## Section One
Content for section one.
## Section Two
Content for section two.
Include YAML front matter at the beginning of documents for metadata:
Required Fields:
post_title - Document headingauthor1 - Primary author namepost_slug - URL-friendly slugmicrosoft_alias - Author's identifier (adapt to your organization)featured_image - Featured image URL or pathcategories - Document categories (from controlled list)tags - Searchable tagsai_note - Indicator if AI was used in creationsummary - Brief document synopsis (1-2 sentences)post_date - Publication date (YYYY-MM-DD)Example:
---
post_title: "Getting Started with TypeScript"
author1: "Jane Doe"
post_slug: "getting-started-typescript"
microsoft_alias: "jdoe"
featured_image: "./images/typescript-hero.png"
categories: ["Development", "TypeScript"]
tags: ["typescript", "tutorial", "beginners"]
ai_note: "AI-assisted writing"
summary: "A beginner-friendly guide to setting up and using TypeScript in your projects."
post_date: 2025-01-15
---
## Introduction
Content starts here...
❌ Don't:
✅ Do:
Before committing markdown files, verify:
---
post_title: "API Authentication Guide"
author1: "John Smith"
post_slug: "api-authentication-guide"
microsoft_alias: "jsmith"
featured_image: "./images/api-auth.png"
categories: ["API", "Security"]
tags: ["authentication", "api", "security", "jwt"]
ai_note: "Human-written"
summary: "Comprehensive guide to implementing authentication in REST APIs."
post_date: 2025-01-15
---
## Introduction
This guide covers authentication strategies for REST APIs, focusing on
JWT-based authentication and best practices for secure implementation.
## Authentication Methods
### Token-Based Authentication
Token-based authentication uses cryptographic tokens to verify user identity:
- **Stateless** - No server-side session storage required
- **Scalable** - Works well with distributed systems
- **Flexible** - Can include custom claims and metadata
### Implementation Example
Here's a basic JWT authentication flow:
\`\`\`typescript
import jwt from 'jsonwebtoken';
interface TokenPayload {
userId: string;
email: string;
role: string;
}
function generateToken(payload: TokenPayload): string {
return jwt.sign(payload, process.env.JWT_SECRET!, {
expiresIn: '24h'
});
}
function verifyToken(token: string): TokenPayload {
return jwt.verify(token, process.env.JWT_SECRET!) as TokenPayload;
}
\`\`\`
## Security Best Practices
Follow these guidelines to ensure secure authentication:
1. **Use HTTPS only** - Never send tokens over unencrypted connections
2. **Set appropriate expiration** - Balance security and user experience
3. **Rotate secrets regularly** - Change signing keys periodically
4. **Validate all inputs** - Prevent injection attacks
## Comparison Table
| Method | Security | Complexity | Scalability |
|--------|:--------:|:----------:|:-----------:|
| JWT | High | Medium | Excellent |
| Session | Medium | Low | Good |
| OAuth 2.0 | Very High | High | Excellent |
## Next Steps
To implement authentication in your project:
- Review the [JWT documentation](https://jwt.io/introduction)
- Set up environment variables for secrets
- Implement token refresh mechanism
- Add rate limiting to authentication endpoints
For more information, see the [Security Best Practices Guide](./security-guide.md).
Add markdown linting to your CI pipeline:
# .github/workflows/lint-docs.yml
name: Lint Documentation
on: [pull_request]
jobs:
lint-markdown:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Lint markdown files
uses: avto-dev/markdown-lint@v1
with:
args: '**/*.md'
Version History:
github.com/github/awesome-copilot/instructions/markdown.instructions.mdReview Schedule: Quarterly review recommended to incorporate new best practices
Feedback: Submit improvements via project issue tracker
