layout: page description: Manage and Write Content with Jekyll title: Manage Pages tagline: Manage and Write Content with Jekyll group: pages toc: true


:website: jekyllrb.com/docs/posts/ :revnumber: 3.2.1

//Ref :liquid-date-formats: docs.shopify.com/themes/liquid-documentation/filters/additional-filters#date

.boxShadow

In addition to writing posts, another thing you may want to do with your Jekyll site is create static pages. By taking advantage of the way Jekyll copies files and directories, this is easy to do.

The Front Matter

The front matter is where Jekyll starts to get really cool. Any file that contains a `YAML front matter block` will be processed by Jekyll as a special file. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines.

Here is a very basic example:

source, yaml


layout: post title: Blogging Like a Hacker



Between these triple-dashed lines, you can set predefined variables (see below for a reference) or even create custom ones of your own. These variables will then be available to you to access using Liquid tags both further down in the file and also in any layouts or includes that the page or post in question relies on.

WARNING

If you use UTF-8 encoding, make sure that no `BOM header` characters exist in your files or very, very bad things will happen to Jekyll. This is especially relevant if you’re running`Jekyll on Windows`.

NOTE

If you want to use `Liquid tags and variables` but don’t need anything in your front matter, just leave it empty! The set of triple-dashed lines with nothing in between will still get Jekyll to process your file. (This is useful for things like CSS and RSS feeds!)

Predefined Global Variables

There are a number of predefined global variables that you can set in the front matter of a page or post.

width=“100%”, cols=“4,8”,options=“header”, role=“table-responsive mt-3”

|======================================================================= |Variable |Description |`layout` |If set, this specifies the layout file to use. Use the layout file name without the file extension. Layout files must be placed in the `_layouts` directory.

|`permalink` |If you need your processed blog post URLs to be something other than the site-wide style (default `/year/month/day/title.html`), then you can set this variable and it will be used as the final URL.

|`published` |Set to false if you donÔÇÖt want a specific post to show up when the site is generated. |=======================================================================

Custom Variables

Any variables in the front matter that are not predefined are mixed into the data that is sent to the Liquid templating engine during the conversion. For instance, if you set a title, you can use that in your layout to set the page title:

source, html

<!DOCTYPE HTML> <html>

<head>
  <title>{% raw %}{{ page.title }}{% endraw %}</title>
</head>
<body>
  ...

Predefined Variables for Posts

These are available out-of-the-box to be used in the front matter for a post.

width=“100%”, cols=“4,8”,options=“header”, role=“table-responsive mt-3”

|======================================================================= |Variable |Description |`date` |A date here overrides the date from the name of the post. This can be used to ensure correct sorting of posts. A date is specified in the format `YYYY-MM-DD HH:MM:SS +/-TTTT`; hours, minutes, seconds, and timezone offset are optional.

a| `category`

`categories`

|Instead of placing posts inside of folders, you can specify one or

more categories that the post belongs to. When the site is generated the post will act as though it had been set with these categories normally. Categories (plural key) can be specified as a en.wikipedia.org/wiki/YAML#Lists[YAML list] or a comma-separated string.

|`tags` |Similar to categories, one or multiple tags can be added to a post. Also like categories, tags can be specified as a YAML list or a comma-separated string. |=======================================================================

NOTE

*Don't repeat yourself!*

If you don't want to repeat your frequently used front matter variables over and over, just define `Front Matter defaults` for them and only override them where necessary (or not at all). This works both for predefined and custom variables.

Working with drafts

Drafts are posts without a date. They're posts you're still working on and don't want to publish yet. To get up and running with drafts, create a `&#x5F;drafts` folder in your site's root (as described in the `docs structure`

section) and create your first draft:
source, text

|– _drafts/ | |– a-draft-post.md


To preview your site with drafts, simply run `jekyll serve` or `jekyll build` with the `–drafts` switch. Each will be assigned the value modification time of the draft file for its date, and thus you will see currently edited drafts as the latest posts.

Creating pages

In addition to [writing posts](../posts/), another thing you may want to do with your Jekyll site is create static pages. By taking advantage of the way Jekyll copies files and directories, this is easy to do.

Homepage

Just about every web server configuration you come across will look for an HTML file called `index.html` (by convention) in the site's root folder and display that as the homepage. Unless the web server you’re using is configured to look for some different filename as the default, this file will turn into the homepage of your Jekyll-generated site.

NOTE

*Use layouts on your homepage!*

Any HTML file on your site can use layouts and/or includes, even the homepage. Common content, like headers and footers, make excellent candidates for extraction into a layout.

Where additional pages live

Where you put HTML or Markdown files for pages depends on how you want the pages to work. There are two main ways of creating pages:

  • Place named HTML or Markdown files for each page in your site's root folder.

  • Create a folder in the site's root for each page, and place an index.html

or index.md file in each page folder.

Both methods work fine (and can be used in conjunction with each other), with the only real difference being the resulting URLs.

Named HTML files

The simplest way of adding a page is just to add an HTML file in the root directory with a suitable name for the page you want to create. For a site with a homepage, an about page, and a contact page, here’s what the root directory and associated URLs might look like:

source, text

. |– _config.yml |– _includes/ |– _layouts/ |– _posts/ |– _site/ |– about.html # => example.com/about.html |– index.html # => example.com/ |– other.md # => example.com/other.html └── contact.html # => example.com/contact.html


Named folders containing index HTML files

There is nothing wrong with the above method. However, some people like to keep their URLs free from things like filename extensions. To achieve clean URLs for pages using Jekyll, you simply need to create a folder for each top-level page you want, and then place an `index.html` file in each page’s folder. This way the page URL ends up being the folder name, and the web server will serve up the respective `index.html` file. Here's an example of what this structure might look like:

source, text

. ├── _config.yml ├── _includes/ ├── _layouts/ ├── _posts/ ├── _site/ ├── about/ | └── index.html # => example.com/about/ ├── contact/ | └── index.html # => example.com/contact/ |── other/ | └── index.md # => example.com/other/ └── index.html # => example.com/


This approach may not suit everyone, but for people who like clean URLs it’s simple and it works. In the end, the decision is yours!

NOTE

*Use permalink Front Matter Variable!*

Clean URLs can also be achieved using the `permalink` front matter variable. In the example above, using the first method, you can get URL `example.com/other` for the file `other.md` by setting this at the top of the file: `permalink: /other`

Static Files

In addition to renderable and convertible content, we also have `static files`. A static file is a file that does not contain any YAML front matter. These include images, PDFs, and other un-rendered content.

They're accessible in Liquid via `site.static&#x5F;files` and contain the following metadata:

width=“100%”, cols=“4,8”,options=“header”, role=“table-responsive mt-3”

|======================================================================= |Variable |Description |`file.path` |The relative path to the file.

|`file.modified&#x5F;time` |The `Time` the file was last modified.

|`file.extname` |The extension name for the file, e.g. `.jpg` for `image.jpg` |=======================================================================

Assets

Jekyll provides built-in support for Sass and can work with CoffeeScript via a Ruby gem. In order to use them, you must first create a file with the proper extension name (one of `.sass`, `.scss`, or `.coffee`) and ***start the file with two lines of triple dashes***, like this:

source, sass



// start content .my-definition

font-size: 1.2em

Jekyll treats these files the same as a regular page, in that the output file will be placed in the same directory that it came from. For instance, if you have a file named `css/styles.scss` in your site's source folder, Jekyll will process it and put it in your site's destination folder under `css/styles.css`.

NOTE

Jekyll processes all Liquid filters and tags in asset files

If you are using `Mustache` or another `JavaScript templating language` that conflicts with the `Liquid template syntax`, you will need to place `{% raw %}`

and `{% endraw %}` tags around this code.

Sass/SCSS

Jekyll allows you to customize your Sass conversion in certain ways.

Place all your partials in your `sass&#x5F;dir`, which defaults to `<source>/&#x5F;sass`. Place your main SCSS or Sass files in the place you want them to be in the output file, such as `<source>/css`. For an example, take a look at [this example site using Sass support in Jekyll].

If you are using Sass `@import` statements, you'll need to ensure that your `sass&#x5F;dir` is set to the base directory that contains your Sass files. You can do that thusly:

source, yaml

sass:

sass_dir: _sass

The Sass converter will default the `sass&#x5F;dir` configuration option to `&#x5F;sass`.

[example-sass]: github.com/jekyll/jekyll-sass-converter/tree/master/example

NOTE

*sass&#x5F;dir is only used by Sass.*

Note that the `sass&#x5F;dir` becomes the load path for Sass imports, nothing more. This means that Jekyll does not know about these files directly, so any files here should not contain the YAML Front Matter as described above nor will they be transformed as described above. This folder should only contain imports.

You may also specify the output style with the `style` option in your `&#x5F;config.yml` file:

source, yaml

sass:

style: compressed

These are passed to Sass, so any output style options Sass supports are valid here, too.

Coffeescript

To enable Coffeescript in Jekyll 3.0 and up you must

  • Install the `jekyll-coffeescript` gem

  • Ensure that your `&#x5F;config.yml` is up-to-date and includes the following:

source, yaml

gems:

- jekyll-coffeescript