Jekyll Tutorial—Getting Started Quickly

In this article, we will use the simplest Jekyll project to demonstrate how to create a project and explain the basic structure of the project. Some details may not be in-depth here, but will be explained one by one in subsequent blog posts.

Create and run the project

Create a new project and execute the following command:

    $ [jekyll](/search?q=jekyll) new learn-jekyll

After the execution is completed, we successfully created a Jekyll project named learn-jekyll .

Go to the directory and execute the following command:

    $ bundle exec jekyll server

The project enters the construction phase. After success, open the following link in the browser:

    http://127.0.0.1:4000/

A brand new website is built.

When the browser accesses the above link, the terminal will output some logs, and Ctrl + C can terminate the project.

basic structure

Jekyll also follows the basic principle of "convention over configuration", so the cost of getting started is extremely low.

In the newly created project directory, there are two main folders:

_posts- Used to store blog posts
_site- Used to store static files generated after the project is built. That is to say, all files of the static website will come from here. CSS files, JS files and image files will be stored in the folder in this directory assets. We can directly deploy the files in this directory

In addition to this, there are some other files:

_config.ymlIt is the configuration file of the project. Some global configurations will be written in this file, such as collections (will be explained in subsequent tweets), default files/paths, etc. In short, there are many things that can be customized here
.gitignoreIt will be automatically generated when creating a project, and files that do not need to be included in CVS are stored here.
Gemfile& Gemfile.lockstores the Ruby gems that the project depends on

We will focus _config.ymlon Gemfilethese two files later, because only by understanding them can Jekyll play its best role.

You may have noticed that several Markdown files are generated in the project root directory. The reason why Markdown is loved by everyone is that it is more concise than HTML and easier to edit than rich text.

We have already mentioned when introducing the installation of Jekyll : Jekyll supports two file formats: HTML and Markdown. However, the files required for static websites must be in html format, so the about.markdownand here index.markdownwill be converted into html files when executing the build and placed in _sitethe directory.

Other agreed directories

In addition to the directories mentioned above, we can also add others, and Jekyll will automatically recognize them and perform corresponding processing.

_data- Data files required by the website (equivalent to a small database)
_drafts- Blog drafts will not be built into static files and will not be made public
_layouts- Layout file, equivalent to the "parent class" of a type of page (such as a blog page)
_includes- Small module, which is part of the HTML file and can be reused in multiple pages, such as navigation, footer, etc.

Common commands

bundle exec jekyll serve- Suitable for the development stage. Building and running the project actually starts a web server that comes with Jekyll. You can use this command to generate the static files required by the website and access them directly in the browser.
jekyll build- Suitable for the deployment stage, only building the static files required by the website
jekyll help- View help, usagejekyll help <command name>

We know that after installing Jekyll, there is jekyllthis executable command in the system environment, and its usage is very simple:

    jekyll command [argument] [option] [argument_to_option]
    
    Examples:
        jekyll new site/ --blank
        jekyll serve --config _alternative_config.yml
    

To view jekyllall usages of , you can view the official documentation . Here are a few of the more commonly used ones:

jekyll new PATH- Create new project
jekyll new PATH --blank- Create new empty project
jekyll buildor jekyll b- build the project to generate a deployable _sitedirectory
jekyll serveOr jekyll s- Build and run the project, it will automatically monitor file changes and does not need to be executed repeatedly.
jekyll clean- Clear all build artifacts
jekyll new-theme- Create a new theme scaffold
jekyll doctor- Diagnosis, output all obsolete dependency packages or problematic configurations

OK, the above is the basic introduction of Jekyll, and the specific usage of each part will be explained in detail later.