Link Search Menu Expand Document
Build and customize a website with Jekyll

Site Structure

The biggest difference between site generators is the tools and capabilities they offer to write, publish, and monitor your content in the desired style. Jekyll has a standard structure to find the content of your website and display them properly. The information here is from Official Jekyll documentation. A basic Jekyll website usually has the following directory structure:

.
├── _config.yml
├── _data
│   └── members.yml
├── _drafts
│   ├── begin-with-the-crazy-ideas.md
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2021-05-23-why-I-chose-UBC.md
|   ├── 2021-01-12-welcome-to-jekyll.md
├── _sass
|   ├── _base.scss
|   └── _layout.scss
├── _site
├── 404.html
├── about.md
├── .jekyll-cache
│   └── Jekyll
│       └── Cache
│           └── [...]
├── .jekyll-metadata
├── Gemfile
├── Gemfile.lock
└── index.html

Gem-based themes have different file structures. Learn more about them

Upon commanding jekyll serve, Jekyll goes through the files in the site directory and compiles them to create the HTML and CSS files required to build the website. The results will be stored in the folder _site.

  • _config.yml stores configuration data of your site including the site’s title, logo, description, admin’s email and much more. You can also specify information such as Twitter handler and Google Analytics code and later recall them dynamically in other site pages.

  • _data can be populated with well-formatted data files (such as YAML .yml files) and access later in the site.data variable. For example, you can write your resume here and regularly update it.

  • _drafts is where you can keep draft posts. These posts follow the same format as your published posts. When they are ready to be published, you can easily drag and drop them into _posts folder.

  • _includes contains reusable content that can be mixed and matched by your layout and posts, such as the footer and header of your site.

  • _layouts are templates that wrap your website’s posts. You can build different templates for different parts of your website. In the layouts, you can specify the position of your content and the look of the webpage.

  • _posts contains all of your posts usually in Markdown format. You can customize the permanent link for each post but is retrieved from the name of the files by default. The naming convention of these files is important and must follow the format: YEAR-MONTH-DAY-title.md.

  • _sass includes .sass files, an extension of CSS files, used to format the layout of webpages. These files are later processed into main.css and define the style of your site, such as the size, type, and colour of fonts in each webpage.

  • _site is the directory that contains all the files generated by Jekyll. You should not add any files to this directory or delete them from it. You also do not need to sync this directory on Github. If you are serving your website on other hosts, you only need to copy the files in this folder to the webserver and you are done. Any files such as CSS, JS, and images will also end up here in an assets folder.

  • .jekyll-cache and .jekyll-metadata are hidden folders that contain a cache of the generated pages for faster serving and keeps track of the files created by Jekyll and the one that has been modified since the site was last built. You do not need to modify these files or sync them on Github.

  • 404.html is the HTML file that will be shown when they are directed to a page on your site that does not exist.

  • Gemfile and Gemfile.lock store all of the gem dependencies for your site.

  • index.html or index.md is the default landing page of your site.

  • .gitignore contains instructions for your source control system to ignore files/folders. You need to add the following addresses to gitignore:

Input

_site
.sass-cache
.jekyll-metadata
*.DS_Store
.jekyll-cache

You can create other directories in this directory and direct the Jekyll compiler to use them while building your website. You can make directories, such as assets, to keep fonts, images, and documents you need to show on your website.

Table of contents