_](<URL>)` directly underneath the relevant heading. For example, to add a Rust web server tutorial under a new category, you would append: ```markdown #### 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`](https://github.com/codecrafters-io/build-your-own-x/blob/main/README.md) and parses it into technology groups: ```python 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: ```bash #!/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`](https://github.com/codecrafters-io/build-your-own-x/blob/main/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`](https://github.com/codecrafters-io/build-your-own-x/blob/main/.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`](https://github.com/codecrafters-io/build-your-own-x/blob/main/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 \`<technology>\``), 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`](https://github.com/codecrafters-io/build-your-own-x/blob/main/README.md) organizes entries by technology rather than language, you must scan the bullet lists under each `#### Build your own \`<technology>\`` 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 \`<New Technology>\``. Place your tutorial bullet immediately underneath this new heading, following the standard bullet format.

# How Tutorials Are Organized in the Build Your Own X Repository > Discover how tutorials are organized in the Build Your Own X repository. Learn about the hierarchical structure, Markdown headings, and formatting for each language and project. - Repository: [CodeCrafters/build-your-own-x](https://github.com/codecrafters-io/build-your-own-x) - Tags: how-to-guide - Published: 2026-02-23 --- **Tutorials in the Build Your Own X repository are organized hierarchically within the single [`README.md`](https://github.com/codecrafters-io/build-your-own-x/blob/main/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`](https://github.com/codecrafters-io/build-your-own-x/blob/main/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: ```markdown * [**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: ```markdown * [**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`](https://github.com/codecrafters-io/build-your-own-x/blob/main/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 `* [****: __](<URL>)` directly underneath the relevant heading. For example, to add a Rust web server tutorial under a new category, you would append: ```markdown #### 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`](https://github.com/codecrafters-io/build-your-own-x/blob/main/README.md) and parses it into technology groups: ```python 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: ```bash #!/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`](https://github.com/codecrafters-io/build-your-own-x/blob/main/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`](https://github.com/codecrafters-io/build-your-own-x/blob/main/.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`](https://github.com/codecrafters-io/build-your-own-x/blob/main/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 \`<technology>\``), 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`](https://github.com/codecrafters-io/build-your-own-x/blob/main/README.md) organizes entries by technology rather than language, you must scan the bullet lists under each `#### Build your own \`<technology>\`` 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 \`<New Technology>\``. Place your tutorial bullet immediately underneath this new heading, following the standard bullet format.