Project structure

Most people only edit _config.yml, the page files, _projects/ and _posts/.

izar-jekyll/
├── _config.yml          Your name, links, footer, contact form, colour scheme and switches
├── index.md             The home page: a list of sections
├── works.md             The Works page
├── notes.md             The Notes page
├── notes-tags.md        The Topics page: notes grouped by topic
├── contact.md           The Contact page
├── thank-you.md         Where visitors land after sending the form
├── 404.html             The "page not found" page
├── blocks.html          The /blocks/ catalogue of sections
├── _projects/           One file per project (Works)
├── _posts/              One file per note, named YYYY-MM-DD-title.md
├── _data/
│   ├── strings.yml      Every word the theme prints by itself
│   ├── blocks.yml       The list shown on /blocks/
│   └── examples/        The snippets shown on /blocks/
├── _layouts/
│   ├── default.html     The HTML shell every page uses
│   ├── home.html        Header, sections, footer
│   ├── page.html        The same, for Works, Notes and Contact
│   ├── post.html        One note
│   └── project.html     One project
├── _includes/
│   ├── sections/        One file per section type, with its fields listed at the top
│   ├── css/             All the styles, as plain CSS
│   │   ├── colors.css   The colour scales
│   │   ├── theme.css    The colour names the theme uses, light and dark
│   │   ├── scale.css    Type sizes, spacing, layout widths, fonts
│   │   └── sections/    One stylesheet per section type
│   ├── icons/           The icons (SVG)
│   ├── header.html      Name, menu, profiles, light/dark switch
│   └── footer.html      Closing call to action and profiles
├── assets/
│   ├── fonts/           JetBrains Mono (self-hosted)
│   ├── img/             Your pictures and the sharing image
│   └── favicon.svg
├── wrangler.jsonc       Settings for Cloudflare
└── Gemfile              For running the site on your computer

How a page is built

index.md, works.md, notes.md and contact.md have no text of their own. Their sections: list says which sections appear, in which order, with which words. The layout reads the list and renders each section from _includes/sections/<type>.html. Anything you write below the front matter is shown after the sections.

Only the CSS of the section types a page uses is added to it, and all the CSS sits inside the page. There’s no separate stylesheet to download.

Files that don’t go into your site

_config.yml tells Jekyll to leave out README.md, LICENSE, CREDITS.md, Gemfile, wrangler.jsonc and a few other files, so they never appear in _site/.