Skip to content

Files & Directories Guide

Jump to bottom
Luna edited this page Dec 4, 2019 · 1 revision

General Overview

Once you've finished installing and setting up the website on your computer, the directory structure in the project's top directory (aka the root directory) will look something like this:

├── _data
│   └── agendas
├── _docs
├── _includes
│   ├── sidebars
│   │   └── blocks
│   └── subheaders
├── _layouts
├── _ref
│   └── _docs
├── _sass
│   └── partials
│       └── media
├── assets
│   ├── files
│   └── images
│       ├── get2010
│       ├── get2011
│       ├── get2012
│       ├── get2013
│       ├── get2014
│       ├── get2015
│       └── get2016
├── collections
│   ├── _agenda2012
│   ├── _awards2016
│   ├── _awards-presenters2010
│   ├── _breakout-leaders2010
│   ├── _discussion-leaders2010
│   ├── _discussion-leaders2012
│   ├── _discussion-leaders2013
│   ├── _expos2016
│   ├── _judges2016
│   ├── _labs2013
│   ├── _labs2014
│   ├── _labs2016
│   ├── _media-partners2016
│   ├── _moderators2010
│   ├── _organizers2015
│   ├── _organizers2016
│   ├── _prototypes2010
│   ├── _speakers2010
│   ├── _speakers2011
│   ├── _speakers2012
│   ├── _speakers2013
│   ├── _speakers2014
│   ├── _speakers2015
│   ├── _speakers2016
│   ├── _sponsors2010
│   ├── _sponsors2011
│   ├── _sponsors2012
│   ├── _sponsors2013
│   ├── _sponsors2014
│   ├── _sponsors2015
│   └── _sponsors2016
├── favicon
├── get2010
│   └── images
├── get2011
│   └── images
├── get2012
│   └── images
├── get2013
│   └── images
├── get2014
│   └── images
├── get2015
│   └── images
├── get2016
│   └── images
└── scripts

The root directory will also contain some important files, such as:

# Important files
├── _config.yml
├── _config_local.yml
├── Gemfile
├── index.md

The root directory will be the folder set-up when you ran the initial git clone. So if your project is stored in /username/sites/pgpconference/, it's the pgpconference directory.

Directory Explanations

  • assets is where media files such as images, videos, etc live
    • Some of these files may also be in their respective get200x folders, as this reflects the url structure of the original site.
    • Future years should stick with putting the files into the assets folder
  • collections contains the various collections directories.
    • The names of the folders should be self-explanatory
  • _data contains navigation.yml, events.yml and the agendas directory.
    • events.yml contains the data for the Past/Future Events sidebar section
    • agendas contains the data for each year's Agenda pages
      • Note: the 2012 Agenda data is actually in collections/_agenda2012, due to the page's two-column formatting
  • _docs contains all the documentation for the repo
    • Note: this is managed in the separate Wiki Repo
  • favicon contains relevant files for the favicon
  • get200x contains the pages for that specific year's conference
  • _includes contains template files for things like the header, footer, nav menu, etc. These can be mixed in with differen layouts.
  • _layouts contains basic page layouts
  • _sass is where the styles for the site live. Sass (Syntactically Awesome Style Sheets) is a pre-processor for CSS. The central file is minima.scss, and the actual code is found in the various files in the partials directory. See below for more info.
  • _site is the compiled version of the site. You can basically ignore this. Always make sure this is listed in your .gitignore file. You do not want to commit this to the repo.
  • scripts contains javascript files essential for various site features
  • styles contains any extra styles that needed to be incorporated, such as Bootstrap or other css files that are loaded separately from the main scss files
  • webfonts contains the font files used by FontAwesome (important for Mobile Menu and possible other icons)
  • 2012-2016 auto-generated archive folders and files.

Important Directories

Most of these should be pretty self explanatory. You'll notice that many of the files are in Markdown. Jekyll magically builds these files into the html files in the _site directory. If you want to exclude a file (say for example the readme or docs files), go to the exclude section of _config.yml.

Top/Root Directory

The top directory will be whatever you named the folder locally or what you see when you go to the Staging Repo. For example, if I've cloned or downloaded the folder into the /username/sites/ folder on my computer, then the root directory would be something like /username/sites/pgpconference. You can tell you're in the root folder, if it looks like the directory structure at the top of this doc.

Data

Right now the only file in _data is navigation.yml. This allows you to modify the main nav menu, and could also be used to create additional menus.

Layouts

The html files in the _layouts directory allow you to create custom templates for different page/post types.

  • Right now almost everything is using the default.html layout.
  • A cool feature of layouts is that they can extend other layouts. Pretty much all of the layouts currently inherit the default.html layout - as it sets the basic scaffolding for the pages on the site.

Includes

The _includes directory contains the various building blocks of the site (such as page head, footer, header and nav menu, etc), as well as the template files that generate specific pages.

  • head.html is where all the javascript and css files are loaded, as well as where SEO and other relevant info is traditionally defined (though that's mostly being handled by jekyll plugins in our case)
  • footer and nav.html are exactly what they sound like. There isn't a separate header file, since the header essentially is the nav menu.
  • agenda-detailed.html is used for the 2010 and 2011 conferences
  • agenda-double.html is used for the 2012 conferences
  • agenda.html is used for 2013-2016
  • The rest should be fairly self-explanatory

Important Files

  • .gitignore tells Git what to ignore. This is great if you have local files or folders that are helpful for you, but not relevant to anyone else. (ex: I have a scratch directory where I keep code snippets or unidentified miscellaneous code).
  • _config.yml contains various settings for things like: site info, plugins, collections, and backend configuration.
  • _config_local.yml lets you override the main config file. See Building & Serving the Site - Secondary Config File for more info.
  • Gemfile manages packages, plugins, and Ruby "gems"
    • There is an accompanying Gemfile.lock. Ignore this file, unless you know that you know for sure that you need to edit it.
  • index.md is the site's homepage

Scripts & Styles

Unless you are a site admin or web developer, this section is almost certainly irrelevant for you.

Scripts Directory

The scripts directory contains the following files:

  • prefixtree.js or prefixtree.min.js - auto-prefixes the rendered CSS code, for compatibility with older browsers

SASS (Styling the Site)

Sass lets you use features that don't exist in CSS yet like variables, nesting, mixins, inheritance and other nifty goodies that make writing CSS fun again.

The styles for the site all live in the _sass directory, however the main stylesheet for the site is assets/style.scss. This is the file that Jekyll will compile into our actual CSS code. The rest of the stylesheets are located under the _sass/_partials directory.

At present, this folder contains the following:

_sass
├── minima.scss
└── partials
    ├── _agenda.scss
    ├── _base.scss
    ├── _collections.scss
    ├── _common.scss
    ├── _custom.scss
    ├── _get2016.scss
    ├── _home.scss
    ├── _labs.scss
    ├── _layout.scss
    ├── _media.scss
    ├── _nav.scss
    ├── _subheader.scss
    ├── _syntax-highlighting.scss
    ├── _variables.scss
    └── media
        ├── _min-width-1024.scss
        ├── _min-width-1200.scss
        ├── _min-width-425.scss
        ├── _min-width-576.scss
        ├── _min-width-768.scss
        └── _min-width-920.scss

The main file to be aware of here is _variables.scss, as that contains various presets which you can use or expand to make your life easier when styling the site.

Clone this wiki locally