This document establishes writing style, formatting conventions, and content standards for the IT-Journey repository.
Educational and Encouraging
Example:
✅ Good: "Let's explore how Jekyll collections work. You'll find they make content organization much easier."
❌ Avoid: "Jekyll collections are a feature that developers should understand."
Clear and Concise
Example:
✅ Good: "Jekyll converts Markdown files into static HTML pages."
❌ Avoid: "Markdown files are converted into static HTML pages by Jekyll."
Inclusive and Professional
For Beginners:
For Intermediate Learners:
For Advanced Users:
Use ATX-style headings with a space after the #:
# H1: Page Title (one per document)
## H2: Major Sections
### H3: Subsections
#### H4: Sub-subsections
##### H5: Minor subdivisions
###### H6: Rarely used
Guidelines:
Examples:
✅ Good: "## Setting Up Your Development Environment"
❌ Avoid: "## Setup" (too vague)
❌ Avoid: "## SETTING UP YOUR DEVELOPMENT ENVIRONMENT" (all caps)
This is the first paragraph. It introduces a concept.
This is the second paragraph. It expands on the concept with details.
This is the third paragraph. It provides an example or conclusion.
Unordered Lists:
Use - for consistency:
- First item
- Second item
- Third item
- Nested item
- Another nested item
- Fourth item
Ordered Lists:
Use 1. for all items (Markdown auto-numbers):
1. First step
1. Second step
1. Third step
1. Sub-step
1. Another sub-step
1. Fourth step
Task Lists: For checklists and to-do items:
- [ ] Incomplete task
- [x] Completed task
- [ ] Another task
Bold for emphasis and key terms:
**Important:** Always test your changes locally before committing.
Italic for subtle emphasis or citations:
The *Jekyll documentation* recommends using collections for this purpose.
Avoid:
Internal Links (within repository):
See the [Repository Structure](architecture/REPOSITORY_STRUCTURE.md) for details.
[Quest documentation](../pages/_quests/README.md)
External Links:
Read the [Jekyll documentation](https://jekyllrb.com/docs/) for more information.
Link Best Practices:
<!-- Reference-style links -->
Check out [Jekyll docs][jekyll] and [GitHub Pages][gh-pages].
[jekyll]: https://jekyllrb.com/docs/
[gh-pages]: https://docs.github.com/en/pages
Inline Code: Use backticks for commands, file names, and code snippets:
Run `bundle exec jekyll serve` to start the development server.
Edit the `_config.yml` file to change site settings.
The `collections_dir` variable defines where collections are stored.
Fenced Code Blocks: Always specify the language for syntax highlighting:
```bash
cd it-journey
bundle install
bundle exec jekyll serve
```
```yaml
collections:
posts:
output: true
permalink: /:collection/:year/:month/:day/:slug/
```
```python
def calculate_stats(links):
total = len(links)
broken = sum(1 for link in links if link.is_broken)
return total, broken
```
Supported Languages: bash, python, ruby, javascript, yaml, json, markdown, html, css, scss, liquid, diff
Code Block Best Practices:
Use for callouts, notes, warnings, and quotes:
> **Note:** This feature requires Jekyll 3.9 or higher.
> "The best way to learn is by doing." - Ancient Proverb
> **Warning:** This operation will delete all cached files.
Callout Types:
> **Note:** Informational message
> **Tip:** Helpful suggestion
> **Warning:** Caution about potential issues
> **Important:** Critical information
Use tables for structured data:
| Command | Description | Example |
|---------|-------------|---------|
| `build` | Build the site | `jekyll build` |
| `serve` | Start dev server | `jekyll serve` |
| `clean` | Clean the site | `jekyll clean` |
Table Guidelines:
Use three or more hyphens for section breaks:
---
Use sparingly - prefer headings for structure.
Basic Syntax:
With Width Specification (Jekyll/Kramdown):
{:width="700px"}
Image Best Practices:
assets/images/ with descriptive namesStandard Document Structure:
---
# Frontmatter
title: "Document Title"
date: 2025-10-13T00:00:00.000Z
---
# Document Title
Brief introduction paragraph explaining what this document covers.
## Overview
High-level summary of the content.
## Main Section 1
Detailed content for first major topic.
### Subsection 1.1
More specific information.
### Subsection 1.2
Additional details.
## Main Section 2
Second major topic.
## Conclusion
Wrap-up or next steps.
## Additional Resources
- Links to related documents
- External references
---
**Last Updated**: 2025-10-13
**Version**: 1.0.0
Tutorial Structure:
# Tutorial Title
Brief description of what learner will accomplish.
## Prerequisites
- List required knowledge
- List required tools
- Estimated time to complete
## Step 1: Setup
Clear instructions for first step.
```bash
# Commands with expected output
Expected output or result.
Next step instructions.
How to verify it works.
Common issues and solutions.
Where to go from here.
### Quest Content
**Quest-Specific Format:**
```markdown
# Quest Title
*Quest Level: 0101 | Difficulty: Intermediate | XP: 500*
## The Story
Engaging narrative that frames the technical challenge.
## Quest Objectives
- [ ] Objective 1
- [ ] Objective 2
- [ ] Objective 3
## Prerequisites
Knowledge and tools needed.
## The Journey
### Chapter 1: Beginning
First stage of the quest with instructions.
### Chapter 2: Challenge
Main technical implementation.
### Chapter 3: Mastery
Advanced features or optimization.
## Victory Conditions
How to know you've completed the quest successfully.
## Achievements Unlocked
- Achievement 1: Description
- Achievement 2: Description
## Continue Your Adventure
Links to related quests or next steps.
Naming Conventions:
descriptive-name-component.ext
Examples:
dashboard-overview.png
mermaid-diagram-workflow.svg
quest-level-progression-chart.png
Organization:
assets/
├── images/
│ ├── posts/ # Blog post images
│ ├── quests/ # Quest-specific images
│ ├── docs/ # Documentation images
│ └── screenshots/ # UI screenshots
├── svg/ # SVG graphics and icons
└── gif/ # Animated GIFs (use sparingly)
Optimization:
pngquant or optipngComplete and Runnable: Provide complete, working examples when possible:
# Complete example with context
def check_links(urls):
"""Check a list of URLs and return broken links.
Args:
urls: List of URLs to check
Returns:
List of broken URL dictionaries
"""
broken = []
for url in urls:
if not is_valid(url):
broken.append({'url': url, 'status': 'broken'})
return broken
Snippet with Context: If showing partial code, indicate what’s omitted:
# ... previous code ...
def process_results(results):
# Process the link checking results
total = len(results)
broken = sum(1 for r in results if r['status'] == 'broken')
return {'total': total, 'broken': broken}
# ... additional code ...
Enable in frontmatter and use in content:
---
mermaid: true
---
<div class="mermaid">
graph TD
A[Start] --> B{Decision}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
C --> E[End]
D --> E
</div>
Diagram Guidelines:
Enable in frontmatter and use LaTeX syntax:
---
mathjax: true
---
Inline math: $E = mc^2$
Display math:
$$
\begin{equation}
\frac{d}{dx}(x^2) = 2x
\end{equation}
$$
Binary Level System:
**Quest Level:** 0101 (Binary: 5 in decimal)
Level progression:
- 0000 (0): Foundation
- 0001 (1): Beginner
- 0010 (2): Novice
- 0011 (3): Intermediate
- 0100 (4): Advanced
- 0101 (5): Expert
Fantasy Theme Elements:
⚔️ **The Challenge:** Your task, brave developer...
🏆 **Reward:** Upon completion, you shall gain...
🗺️ **The Path Forward:** Your next adventure awaits...
To Other Collections:
See the [Link Guardian Quest](../../_quests/link-guardian.md) for details.
Within Same Collection:
Check out the [previous post](./2025-10-12-setup-guide.md) in this series.
To Documentation:
Review the [Repository Structure](/docs/architecture/REPOSITORY_STRUCTURE/).
With Context:
According to the [Jekyll documentation](https://jekyllrb.com/docs/collections/), collections are...
Opening in New Tab (when appropriate):
Visit the [IT-Journey website](https://it-journey.dev){:target="_blank"} for more information.
Descriptive and Specific:
✅ Good: 
❌ Avoid: 
❌ Avoid: 
When committing content:
# Good commit messages
git commit -m "Add Jekyll collections tutorial to docs"
git commit -m "Update link guardian quest with troubleshooting section"
git commit -m "Fix broken links in setup documentation"
# Avoid vague messages
git commit -m "Update files"
git commit -m "Changes"
git commit -m "Fix"
When updating existing content:
lastmod field in frontmatterBefore submitting content, verify:
bundle exec jekyll serve)When mentioning files, use inline code:
The main configuration is in `_config.yml`.
Scripts are located in the `scripts/` directory.
Edit `pages/_posts/2025-10-13-my-post.md` to update the post.
Show commands with context:
To start the development server:
```bash
cd it-journey
bundle exec jekyll serve --config _config_dev.yml
This will start Jekyll on port 4002 (configured in _config_dev.yml).
### Expected Output
Show expected output after commands:
```markdown
Run the link checker:
```bash
python3 scripts/link-checker.py --scope website
Expected output:
[INFO] Starting link health check...
[INFO] Scope: website
[INFO] Found 1,250 links to check
[SUCCESS] Link checking completed
[INFO] Results: 1,245 valid, 5 broken
```
Last Updated: 2025-10-13
Version: 1.0.0