The Jekyll recommended in this issue is a simple, blog-enabled, static site generator that is ideal for individual, project, or organizational sites.
Think of it as a file-based CMS, less complex. Jekyll takes your content, renders Markdown and Liquid templates, and spits out a complete static website, ready to be served by Apache, Nginx, or another Web server.
Fast start
< Prerequisites Permalink
Jekyll requires the following:
- Ruby version 2.5.0 or higher
- RubyGems
- GCC and Make
Installation instructions
1 Install all prerequisites.
2 Install jekyll and bundler gems.
gem install jekyll bundler3 Create a new Jekyll site in./myblog.
jekyll new myblog4 Switch to the new directory.
cd myblog5 Build the site and make it available on your local server.
bundle exec jekyll serve6 Navigate to http://localhost:4000
Command Line usage
Jekyll gem enables jekyll you can use executable files in the terminal.
The jekyll program has several commands, but the structure is always:
jekyll command [argument] [option] [argument_to_option]
Examples:
jekyll new site/ --blank
jekyll serve --config _alternative_config.ymlTypically, you will use the jekyll serve for local development and when the jekyll build needs to generate a site for production.
Here are some of the most common commands:
- jekyll new PATH- Creates a new Jekyll site in the specified path with a default gem-based theme. Directories are created as needed.
- jekyll new PATH –blank — Creates a new blank Jekyll site scaffold on the specified path.
- jekyll build or jekyll b- Build your website at once./_site (by default).
- jekyll serve or jekyll s- Build your site whenever the source file changes and makes it available locally.
- jekyll clean- Deletes all generated files: destination folder, metadata file, Sass, and Jekyll cache.
- jekyll help- Displays help, optionally for a given subcommand, such as jekyll help build.
- jekyll new-theme- Creates a new Jekyll theme scaffold.
- jekyll doctor- Outputs any deprecation or configuration issues.
Rendering process
For any Jekyll site, the build session consists of discrete stages in the following sequence – set up the plug-in, read the source file, run the generator, render the template , and finally write the file to disk .
While the above stages are self-explanatory, one stage worth dissecting is the render stage .
The rendering phase can be further divided into three optional phases. Each rendered file passes through one or more of these stages, depending on the file’s content string, front-end content, and extension. These stages are similar to an assembly line, where the output of one stage is the input of subsequent stages:
- Explain the Liquid expression in the file
This phase evaluates the Liquid expression in the current file. By default, the interpretation is very shallow – because any Liquid expression in the resulting output will not be interpreted further. In addition, any Liquid expressions in the front of the file remain unchanged. - Release converter
This phase calls the converter that maps to the current file extension and converts the input string. This is when Markdown converts to HTML and Sass/Scss converts to CSS or CoffeeScript converts to JavaScript and so on. Since this stage is determined by the file’s extension, the Markdown or sas.html in the file will remain unchanged. - Fill layout
By this stage, the source file is considered rendered and it will not be revisited. However, depending on the extension of the file, and therefore on what was previously done, determine whether the output string is taken from the previous stage and put into the layout. While the output of a Sass file or CoffeeScript file is never put into a layout, regular text output can go either way depending on whether the layout has been allocated through the front end.
Page
Pages are the most basic building blocks of content. They are useful for stand-alone content (content that is not date-based or is not a group of content, such as staff or recipes).
The easiest way to add a page is to add an HTML file with an appropriate file name in the root directory. You can also write pages in Markdown using extensions that.md converts to HTML at build time. For a site with a home page, about page, and contact page, the root directory and associated URL might look like this:
.
├── about.md # => http://example.com/about.html
├── index.html # => http://example.com/
└── contact.html # => http://example.com/contact.htmlIf you have a lot of pages, you can organize them into subfolders. When your site is built, the same subfolder that is used to group the pages in the project source will exist in that folder. However, when a page has a different permalinking set up on the front end, the subfolder at_site changes accordingly.
.
├── about.md # => http://example.com/about.html
├── documentation # folder containing pages
│ └── doc1.md # => http://example.com/documentation/doc1.html
├── design # folder containing pages
│ └── draft.md # => http://example.com/design/draft.htmlSubject
Jekyll has an extensive theme system that allows you to customize presentations for your site using community-maintained templates and styles. Jekyll themes specify plug-ins and package assets, layouts, inclusions, and style sheets in a way that can be overridden by your website content.
< Learn about gem based topics
When you create a new Jekyll site (by running jekyll new < PATH> Command), Jekyll installs a site that uses a gem-based theme called Minima.
For GEM-based themes, certain directories of the site (such as the assets, _data, _layouts, _includes, and _sass directories) are stored in the theme’s gem, hidden from your immediate view. However, during the construction of Jekyll, all the necessary directories will be read and processed.
For Minima, you’ll only see the following files in the Jekyll site directory:
.
├── Gemfile
├── Gemfile.lock
├── _config.yml
├── _posts
│ └── 2016-12-04-welcome-to-jekyll.markdown
├── about.markdown
└── index.markdownBundler uses the Gemfile and gemfile.lock files to keep track of the gem and gem versions needed to build the Jekyll site.
Gem-based themes make it easier for theme developers to provide updates to anyone who has a theme gem. When there is an update, the title developer pushes the update to RubyGems.
If you have theme gems, you can (if you wish) run bundle update to update all the gems in your project. Or you can run bundle update < THEME> replace THEME> For the theme name, such as minima, only the theme gem is updated. Any new files or updates (such as stylesheets or inclusions) made by theme developers are automatically pulled into your project.
The goal of a gem based theme is to let you get all the benefits of a strong, constantly updated theme without having all the theme files get in your way and overcomplicate your main concern: creating content.
Overwrite topic Default
Jekyll theme sets default data, layout, inclusion, and style sheet. However, you can override any theme default with your own site content.
To replace the layout or inclusion in a theme, make a copy in your _layouts or _includes directory of the specific file you want to modify, or create the file from scratch and give it the same name as the file you want to overwrite.
For example, if the theme you have chosen has a page layout, you can override the layout of the theme by creating your own page layout _layouts (i.e. _layouts/page.html) in the directory.
To find a file on your computer for a certain topic:
- Runbundle info –path followed by the name of the theme gem, for example bundle info — the default theme of path minimaJekyll.
- This will return the location of the gem based theme file. Minima theme files, for instance, may in the/usr/local/lib/ruby/gems/server/gems/Minima – 2.5.1 macOS.
- Open the subject’s directory in Finder or Explorer:
# On MacOS
open $(bundle info --path minima)
# On Windows
# First get the gem's installation path:
#
# bundle info --path minima
# => C: / Ruby26 - x64 / lib/ruby/gems / 3.1.1 / gems/minima - 2.5.1 < / span >
#
# then invoke explorer with above path, substituting `/` with `\`
explorer C:\Ruby26-x64\lib\ruby\gems\3.1.1\gems\minima-2.5.1
# On Linux
xdg-open $(bundle info --path minima)will open a Finder or Explorer window showing the subject’s files and directories. The Minima theme gem contains the following files:
.
├── LICENSE.txt
├── README.md
├── _includes
│ ├── disqus_comments.html
│ ├── footer.html
│ ├── google-analytics.html
│ ├── head.html
│ ├── header.html
│ ├── icon-github.html
│ ├── icon-github.svg
│ ├── icon-twitter.html
│ └── icon-twitter.svg
├── _layouts
│ ├── default.html
│ ├── home.html
│ ├── page.html
│ └── post.html
├── _sass
│ ├── minima
│ │ ├── _base.scss
│ │ ├── _layout.scss
│ │ └── _syntax-highlighting.scss
│ └── minima.scss
└── assets
└── main.scssWith a clear understanding of the theme file, you can now overwrite any theme file by creating a file with a similar name in the Jekyll site directory.
—END—
Open Source protocol: Apache2.0
