RobotnixAcademy

Unit 01 · lesson

Project Anatomy and Generated Files

A Jekyll site is not just a pile of Markdown files.

The folder names tell you which responsibilities exist.

You have not created all of them yet, but you should start recognizing the architecture now.

A future version of your project

By the middle of the course, your portfolio may resemble:

my-portfolio/
├── _config.yml
├── _data/
├── _includes/
├── _layouts/
├── _posts/
├── _projects/
├── assets/
├── about.md
├── index.md
├── Gemfile
├── Gemfile.lock
└── _site/

Do not create every folder today.

Read the names.

Responsibility map

_config.yml

Site-wide configuration.

_layouts/

Reusable page wrappers/templates.

_includes/

Smaller reusable template fragments.

_data/

Structured YAML/JSON/CSV data Jekyll exposes through site.data.

_posts/

Date-oriented blog posts using Jekyll's post conventions.

collection directories such as _projects/

Custom content types configured as collections.

assets/

CSS, images, JavaScript, and other site resources.

_site/

Generated destination output.

The underscore is a clue, not one universal rule

Many Jekyll special-purpose directories begin with _.

But do not invent a rule that every underscored folder behaves identically.

_site is generated output.

_layouts is source used during rendering.

_posts is source content.

Similar naming. Very different responsibilities.

Inspect your current tree

Print or copy the current project tree.

Then annotate every existing item as one of:

SOURCE CONTENT
SOURCE CONFIGURATION
DEPENDENCY RECORD
GENERATED OUTPUT

If you are unsure, write a question mark and investigate it.

That is better than confidently putting a generated directory under source control because it "looked important."

Generated does not mean useless

You normally edit source, not _site.

But generated output is extremely useful for:

  • debugging;
  • verifying URLs;
  • seeing transformed Liquid/Markdown results;
  • understanding what will be deployed in a simple static deployment.

The correct rule is:

Do not treat generated output as your authoring source. Inspect it when you need build evidence.

Prediction exercise

Later you will add _layouts/default.html.

Predict:

  • Will a folder named _layouts appear as _site/_layouts in the public site?
  • Or will Jekyll use those layout files while generating other pages?

Record your prediction now.

You will test it in Unit 3.

Checkpoint

Create an annotated tree artifact with at least these labels:

  • source;
  • dependency;
  • build-only support;
  • generated destination.

Then explain why deleting _site is fundamentally different from deleting index.html.