How Code Snippets and Collections Are Structured in 30-Seconds-of-Code

Code snippets in 30-seconds-of-code are Markdown files with YAML front-matter stored in content/snippets/<language>/, while collections are YAML files in content/collections/ that group snippets by matching tags, with both consumed by serializers to generate the static site.

The 30-seconds-of-code repository powers a popular learning site through a declarative, file-based content system. Understanding how code snippets and collections are structured in the content files is essential for contributors and developers looking to extend the platform or build similar static-site architectures.

Snippet Files Structure and Front-Matter Schema

File Layout and Organization

All snippet content resides under the content/ directory, organized by programming language. Snippet files reside under content/snippets/<language>/s/ where <language> corresponds to the language slug (e.g., js, python, react). Each language folder contains a snippet-template.md file that serves as the master template for new contributions.

This hierarchy ensures that the src/serializers/ modules can locate and process content by language type, while the template file guarantees consistent formatting across all contributions.

YAML Front-Matter Metadata Fields

Every snippet file begins with a YAML front-matter block that declares metadata driving navigation, SEO, and display logic. The file content/snippets/js/s/array-includes-value.md demonstrates the standard schema:

---
title: How can I check if a JavaScript array includes a specific value?
shortTitle: Array includes value
language: javascript
tags: [array]
cover: bridge-drop
excerpt: Checking if an array includes a specific value is pretty straightforward, except when it comes to objects.
listed: true
dateModified: 2022-09-18
---

Key fields include:

• title and shortTitle: The full heading and a concise version for UI cards.
• language: The language slug matching the folder name.
• tags: An array of tag identifiers used for filtering and collection matching.
• cover: A reference to a visual splash asset.
• excerpt: A one-sentence summary for list pages.
• listed: A boolean controlling visibility in main listings.
• dateModified: Used for cache-busting and SEO freshness.

Body Content and Code Examples

Following the front-matter, the body consists of standard Markdown with fenced code blocks. The site’s parser automatically transforms fenced blocks into highlighted snippets. For example:

const array = [1, 2, 3, 4, 5];
array.includes(3); // true

Snippet Template for Consistency

The content/snippets/js/snippet-template.md file provides a standardized starting point for new contributions. It includes placeholder sections for the title, description, and code examples, ensuring that every new snippet contains the required front-matter fields and follows the established Markdown format.

Collection Files Structure and Tag Matching

Collection YAML Schema

Collections are declarative groupings defined in YAML files under content/collections/. Unlike snippets, these files contain no Markdown body—only metadata that defines how to group existing snippets. The file content/collections/webdev.yaml illustrates the schema:

slug: web-development
title: Web development Articles
shortTitle: Web development
tagMatcher: webdev
description: >-
  The web development article collection contains curated stories, tips,
  questions and answers on a wide variety of topics.
shortDescription: >-
  Discover dozens of web development articles, covering a wide variety of topics
  and technologies.
splash: matcha

Key fields include:

• slug: The URL path segment (e.g., /web-development).
• title and shortTitle: Display titles for the collection page and navigation.
• tagMatcher: A tag pattern that selects snippets belonging to the collection.
• description and shortDescription: Long-form and teaser copy for SEO and UI.
• splash: The name of the splash-image asset used as a visual header.

How Collections Group Snippets via Tag Matching

Collections use the tagMatcher field to automatically include snippets whose front-matter tags array contains the specified value. The collectionContextSerializer (src/serializers/collectionContextSerializer.js) resolves this relationship at build time by filtering the full snippet index against each collection's tag pattern.

This declarative approach means that adding a snippet to a collection requires no manual editing of the collection file—simply tag the snippet appropriately in its front-matter.

Collection Template Structure

The content/collections/collection-template.yaml file provides a boilerplate for new collections. It includes placeholder fields for the slug, tagMatcher, and descriptive text, ensuring that contributors define the necessary metadata for the collection to appear correctly in the site navigation and sidebar.

Build-Time Serialization Process

During the build process, serializer modules transform the static content files into JSON consumed by the Astro front-end. The collectionContextSerializer.js module uses js-yaml to parse collection definitions, while the snippet.js model (src/models/snippet.js) provides the getAllSnippets() helper used to resolve tag relationships.

The serializers validate front-matter, resolve tagMatcher patterns against snippet tags, and output structured data that powers the collection pages, search functionality, and global navigation menu. This architecture enables a fast, content-driven site with zero runtime database dependencies.

Practical Usage Examples

Adding a New JavaScript Snippet

To contribute a new snippet, copy the template and populate the required fields:

# Copy the template

cp content/snippets/js/snippet-template.md content/snippets/js/s/my-new-snippet.md

Edit the file to include specific front-matter:

---
title: How do I flatten a nested array in JavaScript?
shortTitle: Flatten nested array
language: javascript
tags: [array, recursion]
cover: laptop-view
excerpt: Learn how to recursively flatten an array of arbitrary depth.
listed: true
dateModified: 2024-01-15
---

Then add the Markdown body with fenced code blocks. The build pipeline will automatically include the snippet in collections matching the array or recursion tags.

Creating a Custom Collection

To group snippets by a new category, create a collection definition:

# content/collections/algorithms.yaml

slug: algorithms
title: Algorithms Collection
shortTitle: Algorithms
tagMatcher: algorithm
description: >-
  A curated set of algorithmic snippets ranging from sorting to graph traversal.
shortDescription: >-
  Quick, reusable algorithm implementations.
splash: brainfuck-interpreter-part-1

Any snippet with algorithm in its front-matter tags array will automatically appear in this collection. The collectionContextSerializer resolves this relationship during the build, requiring no manual snippet registration.

Summary

• Snippet files reside in content/snippets/<language>/s/ as Markdown files with YAML front-matter containing title, tags, language, and listed fields that drive SEO and navigation.
• Collection files are YAML definitions in content/collections/ that use tagMatcher to dynamically group snippets by their front-matter tags, enabling declarative content organization.
• Serializers in src/serializers/collectionContextSerializer.js process these files at build time, resolving tag relationships and outputting JSON for the Astro front-end.
• Templates at content/snippets/js/snippet-template.md and content/collections/collection-template.yaml enforce consistent metadata structure for contributors.

Frequently Asked Questions

What fields are required in a snippet's front-matter?

Every snippet must include title, shortTitle, language, tags, excerpt, and listed in its YAML front-matter. The dateModified field is also required for cache-busting and SEO, while cover specifies the visual asset displayed on listing pages.

How does a collection know which snippets to include?

Collections use the tagMatcher field to automatically include snippets whose front-matter tags array contains the specified value. The collectionContextSerializer resolves this relationship at build time by filtering the full snippet index against each collection's tag pattern.

Can I create a snippet without adding it to a collection?

Yes. Setting listed: false in the snippet's front-matter hides it from main listings, though it remains accessible via direct URL. However, if the snippet's tags match a collection's tagMatcher, it will still appear in that collection unless specifically excluded by other logic.

Where are the templates for new content located?

The snippet template is located at content/snippets/js/snippet-template.md (with similar templates for other languages), while the collection template resides at content/collections/collection-template.yaml. These files provide boilerplate front-matter and structure to ensure consistency across contributions.

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