finfocus markdown-files.instructions.md

Markdown Documentation Instructions

Documentation files follow specific standards and formatting requirements.

Documentation Standards:

• Use clear, concise language
• Follow Google markdown style guide
• Include proper frontmatter (title, description, layout)
• Use consistent heading hierarchy
• Include table of contents for long documents

Content Organization:

• Start with overview/summary
• Use logical section organization
• Include examples and code snippets
• Provide troubleshooting information
• Link to related documentation

Code Examples:

• Use proper syntax highlighting
• Test all code examples
• Include language identifiers
• Use consistent formatting
• Provide context for examples

Link Management:

• Use relative links within the repository
• Check for broken links regularly
• Use descriptive link text
• Maintain link accuracy

Frontmatter Requirements:

• Include title, description, and layout fields
• Use proper YAML formatting
• Follow Jekyll conventions for docs/
• Include metadata for SEO and navigation

Linting and Validation:

• Pass markdownlint checks
• Follow repository-specific rules
• Use consistent formatting
• Validate links and references

Documentation Updates:

• Keep documentation current with code changes
• Update examples when APIs change
• Review documentation in PR reviews
• Include documentation changes in feature PRs

File Organization:

• Use descriptive filenames
• Follow repository directory structure
• Place files in appropriate directories
• Use consistent naming conventions