readme_guidelines.agents.md•1.8 kB
# README.md Creation Guidelines
As an AI assistant, I will adhere to the following guidelines when creating or modifying a `README.md` file.
## General Guidelines
- Use clear and descriptive headings.
- Employ bullet points and numbered lists for readability.
- Use backticks for inline code and triple backticks for code blocks, specifying the language.
- Keep paragraphs concise.
- Link to relevant files or sections using relative paths.
- Ensure a consistent and instructional tone.
- Favor simple Markdown over complex HTML.
- Do not use first-person or third-person perspective.
## Style Guide
- **Headings:** Use ATX-style headings (`#`, `##`, etc.). The main page title is always H1.
- **Code Blocks:** Always specify the language for syntax highlighting.
- **Lists:** Use hyphens for unordered lists and numbers for ordered lists.
- **Indentation:** Use 2 spaces for indentation.
- **Linting:** Formatting shall be compatible with markdownlint.
## Sections
- **Project Title and Description:** Start with the project name and a brief description.
- **Installation:** Provide clear installation instructions.
- **Usage:** Explain how to use the project with examples.
- **Contributing:** Include guidelines for contributing to the project.
- **License:** Mention the project's license.
## Integration with MkDocs
When a MkDocs site is available for the repository, the `README.md` file should be updated to reflect this.
- **Documentation Section:** Add a "Documentation" section that links to the MkDocs site.
- **Content:** The `README.md` should still contain the following sections:
- A title and a short description of the repository.
- A "TL;DR" section with a brief overview of how to use the project.
- A "License" section.
- An "About" or "Author" section.