How Tutorials Are Organized in the Build Your Own X Repository

Tutorials in the Build Your Own X repository are organized hierarchically within the single README.md file using Markdown headings grouped by technology category, with each entry formatted as a bullet point containing the programming language in bold, the tutorial title in italics, and an external URL.

The Build Your Own X repository by CodeCrafters is a curated collection of step-by-step guides for recreating popular technologies from scratch. Unlike documentation spread across multiple pages, this open-source project consolidates all learning resources into one master document. Understanding how tutorials are organized in the Build Your Own X repository helps contributors submit entries correctly and enables developers to extract the index programmatically.

Hierarchical Structure of the Tutorial Index

The repository employs a three-level Markdown hierarchy that begins at line 42 of README.md. This flat-file architecture keeps the entire index searchable and version-controlled without requiring a database or multiple files.

Level 1: The section header ## Tutorials marks the beginning of the index.

Level 2: Technology subsections use level-four headings formatted as #### Build your own \`. For example, the source code contains #### Build your own `Distributed Systems`and#### Build your own `3D Renderer``, each representing a distinct technology category.

Level 3: Individual tutorials appear as bullet list items immediately following their respective technology headings. This structure repeats consistently throughout the file, creating a clear table of contents that renders natively on GitHub.

Anatomy of a Tutorial Entry

Each tutorial follows a strict markdown pattern to ensure consistency across the index. The standard format is:

* [**Language**: _Descriptive Title_](https://example.com/tutorial-url)

The syntax breaks down as follows:

• Asterisk and space (* ) initiates the bullet list item.
• Language badge wrapped in ** (double asterisks) identifies the programming language (e.g., C++, Rust).
• Title wrapped in _ (underscores) provides the tutorial name in italics.
• URL in parentheses points to the external tutorial or article.

For instance, an entry for a physically based rendering tutorial appears as:

* [**C++**: _Physically Based Rendering: From Theory To Implementation_](http://www.pbr-book.org/)

Contributing New Tutorials

To add a tutorial to the Build Your Own X repository, you must manually edit README.md and insert a new entry following the established pattern. The process requires two steps:

1. Locate the appropriate technology subsection by searching for #### Build your own \``. If the technology does not exist, create a new level-four heading at the end of the tutorials section.

2. Insert a new bullet line using the exact syntax * [**<Language>**: _<Title>_](<URL>) directly underneath the relevant heading.

For example, to add a Rust web server tutorial under a new category, you would append:

#### Build your own `Web Server`

* [**Rust**: _Writing a Minimal HTTP Server in Rust_](https://example.com/minimal-rust-http)

The repository's CI does not enforce a strict schema validation, but adhering to this pattern ensures the index remains machine-readable and visually consistent.

Programmatically Parsing the Index

Because the entire tutorial database resides in one file, you can extract structured data using regular expressions. The following Python script fetches README.md and parses it into technology groups:

import re
import requests

README_URL = (
    "https://raw.githubusercontent.com/codecrafters-io/"
    "build-your-own-x/master/README.md"
)

text = requests.get(README_URL).text

# Find each technology section and its tutorials

sections = re.findall(r"#### Build your own `([^`]+)`\n((?:\* .+\n)+)", text)

for tech, items in sections:
    print(f"\n=== {tech} ===")
    for line in items.strip().splitlines():
        # Extract language, title, link

        m = re.match(r"\* \[\*\*(.+?)\*\*: _(.+?)_ \((.+?)\)", line)
        if m:
            lang, title, url = m.groups()
            print(f"- [{lang}] {title} → {url}")

This script identifies technology headings and captures the subsequent bullet lists, outputting a structured console dump of all tutorials grouped by category.

Automating Entry Generation

You can also automate the insertion of new tutorials using shell scripting. The following Bash script locates a technology section by name and inserts a formatted entry immediately after the header:

#!/usr/bin/env bash

# Append a new tutorial entry to the README

TECH="Web Server"
LANG="Rust"
TITLE="Writing a Minimal HTTP Server in Rust"
LINK="https://example.com/minimal-rust-http"

# Find the line number of the matching section header

section=$(grep -n "#### Build your own \`$TECH\`" README.md | cut -d: -f1)

if [[ -z $section ]]; then
  # Section not found – add it at the end of the file

  echo -e "\n#### Build your own \`$TECH\`\n" >> README.md

  section=$(wc -l <README.md)   # last line number

fi

# Insert the new bullet after the header line

sed -i "$((section+1))i\* [**$LANG**: _${TITLE}_]($LINK)" README.md

Running this script inserts a correctly formatted entry directly under the chosen technology heading, maintaining the repository's organizational structure.

Key Files in the Repository

The organization relies on these critical files:

• README.md – The central document holding the entire tutorial index, beginning at line 42 with the ## Tutorials header. This file serves as the single source of truth for all entries.

• .github/ISSUE_TEMPLATE.md – Provides a template for contributors proposing new tutorials, encouraging the same markdown format used in the main index.

Summary

• All tutorials are stored in the single README.md file, starting at line 42 under the ## Tutorials heading.

• The index uses a three-level hierarchy: main section header, technology-specific subsections (#### Build your own \``), and bullet list entries.

• Each entry follows the strict format: * [**Language**: _Title_](URL).

• No automated schema validation exists in CI, but pattern consistency is essential for maintaining a parseable index.

• The flat-file structure enables easy programmatic extraction using regex patterns.

Frequently Asked Questions

How do I find tutorials for a specific programming language?

Since README.md organizes entries by technology rather than language, you must scan the bullet lists under each #### Build your own \`` section. Each bullet prefixes the programming language in bold (e.g., [Rust] or [Python]) before the italicized title, allowing you to identify relevant tutorials via text search or visual scanning.

What is the exact syntax for submitting a new tutorial?

You must insert a new bullet line under the appropriate technology subsection following this pattern: * [**<Language>**: _<Descriptive Title>_](<External-URL>). The language name goes inside double asterisks, the title inside underscores, and the URL inside parentheses.

Does the repository validate new tutorial submissions automatically?

According to the source code structure, the repository's CI does not enforce a strict schema validation. However, maintaining the established markdown pattern ensures the index remains consistent and easy to parse programmatically by external tools.

Can I create a new technology category if one doesn't exist?

Yes. If your tutorial targets a technology not yet listed, you can create a new subsection by adding a level-four heading: #### Build your own \``. Place your tutorial bullet immediately underneath this new heading, following the standard bullet format.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}