Delete page "meta%2FStyle-guide.-"
@@ -1,121 +0,0 @@
|
|||||||
# Style Guide
|
|
||||||
|
|
||||||
This guide ensures consistency across all tomes within the Tech Grimoire.
|
|
||||||
|
|
||||||
## General Principles
|
|
||||||
|
|
||||||
### Writing Style
|
|
||||||
- Write in clear, concise language
|
|
||||||
- Use active voice
|
|
||||||
- Maintain technical accuracy while being accessible
|
|
||||||
- Keep the magical theme subtle but present
|
|
||||||
- Target an informed technical audience
|
|
||||||
|
|
||||||
### Document Structure
|
|
||||||
- Start with a clear introduction
|
|
||||||
- Use hierarchical headings (H1 → H4)
|
|
||||||
- Include a table of contents for longer articles
|
|
||||||
- End with related links and references
|
|
||||||
- Add tags for cross-referencing
|
|
||||||
|
|
||||||
## Formatting
|
|
||||||
|
|
||||||
### Headers
|
|
||||||
```markdown
|
|
||||||
# Main Title (H1) - One per page
|
|
||||||
## Major Sections (H2)
|
|
||||||
### Subsections (H3)
|
|
||||||
#### Detailed Points (H4)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Code Blocks
|
|
||||||
- Use triple backticks with language specification
|
|
||||||
```markdown
|
|
||||||
```python
|
|
||||||
def example():
|
|
||||||
return "Hello, World!"
|
|
||||||
```
|
|
||||||
```
|
|
||||||
- Use single backticks for inline code: `variable_name`
|
|
||||||
|
|
||||||
### Lists
|
|
||||||
- Use hyphen (-) for unordered lists
|
|
||||||
- Use numbers (1.) for ordered lists
|
|
||||||
- Maintain consistent indentation for nested lists
|
|
||||||
- Two spaces for each nesting level
|
|
||||||
- Keep lists parallel in structure
|
|
||||||
|
|
||||||
### Tables
|
|
||||||
- Use standard markdown tables
|
|
||||||
- Include header row
|
|
||||||
- Align columns meaningfully
|
|
||||||
- Example:
|
|
||||||
```markdown
|
|
||||||
| Command | Description | Example |
|
|
||||||
|---------|-------------|---------|
|
|
||||||
| `ls` | List files | `ls -la`|
|
|
||||||
```
|
|
||||||
|
|
||||||
### Links and References
|
|
||||||
- Use descriptive link text: [Configuration Guide](./config.md)
|
|
||||||
- Prefer relative paths for internal links
|
|
||||||
- Include reference sections for external resources
|
|
||||||
|
|
||||||
## Special Elements
|
|
||||||
|
|
||||||
### Notes and Warnings
|
|
||||||
```markdown
|
|
||||||
> **Note:** Important information that readers should know
|
|
||||||
|
|
||||||
> **Warning:** Critical information about risks or potential issues
|
|
||||||
```
|
|
||||||
|
|
||||||
### Terminal Commands
|
|
||||||
```markdown
|
|
||||||
```bash
|
|
||||||
# Command with explanation
|
|
||||||
command --flag argument # What this does
|
|
||||||
```
|
|
||||||
```
|
|
||||||
|
|
||||||
### Diagrams
|
|
||||||
- Use Mermaid for diagrams
|
|
||||||
- Include both diagram code and description
|
|
||||||
- Example:
|
|
||||||
```markdown
|
|
||||||
```mermaid
|
|
||||||
graph TD
|
|
||||||
A[Start] --> B[End]
|
|
||||||
```
|
|
||||||
```
|
|
||||||
|
|
||||||
## Content Organization
|
|
||||||
|
|
||||||
### File Names
|
|
||||||
- Use lowercase
|
|
||||||
- Replace spaces with hyphens
|
|
||||||
- Be descriptive but concise
|
|
||||||
- Example: `docker-container-optimization.md`
|
|
||||||
|
|
||||||
### Directory Structure
|
|
||||||
- Group related content in directories
|
|
||||||
- Use clear, descriptive directory names
|
|
||||||
- Maximum of 3 levels deep
|
|
||||||
- Include README.md in each directory
|
|
||||||
|
|
||||||
### Tags
|
|
||||||
- Use lowercase for tags
|
|
||||||
- Separate multi-word tags with hyphens
|
|
||||||
- Example: `#machine-learning #neural-networks`
|
|
||||||
|
|
||||||
## Images and Media
|
|
||||||
- Store in designated `/assets` directory
|
|
||||||
- Use descriptive file names
|
|
||||||
- Include alt text for accessibility
|
|
||||||
- Optimize for web viewing
|
|
||||||
- Maximum width: 800px
|
|
||||||
|
|
||||||
## Version Notes
|
|
||||||
- Include last updated date
|
|
||||||
- Note major changes
|
|
||||||
- Reference related tickets/issues
|
|
||||||
Reference in New Issue
Block a user