Update docs
This commit is contained in:
Michael Rose
parent
0d61b26dd4
commit
c1d8c79152
3 changed files with 40 additions and 14 deletions
|
|
@ -19,7 +19,7 @@ Fork the [Minimal Mistakes theme](https://github.com/mmistakes/minimal-mistakes/
|
|||
<img src="{{ base_path }}/images/mm-theme-fork-repo.png" alt="fork Minimal Mistakes">
|
||||
</figure>
|
||||
|
||||
Your Jekyll site should be viewable immediately at <http://USERNAME.github.io>. If it's not, you can force a rebuild by **Customizing Your Site** (see below for more details).
|
||||
**Note:** Your Jekyll site should be viewable immediately at <http://USERNAME.github.io>. If it's not, you can force a rebuild by **Customizing Your Site** (see below for more details).
|
||||
{: .notice--warning}
|
||||
|
||||
If you're hosting several Jekyll based sites under the same GitHub username you will have to use Project Pages instead of User Pages. Essentially you rename the repo to something other than **USERNAME.github.io** and create a `gh-pages` branch off of `master`. For more details on how to set things up check [GitHub's documentation](https://help.github.com/articles/user-organization-and-project-pages/).
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@ sidebar:
|
|||
nav: docs
|
||||
---
|
||||
|
||||
For consistency, Minimal Mistake's folder and file structure tries to remain close to a *default* Jekyll site. There's nothing clever here to be found :wink:.
|
||||
Nothing clever here :wink:. Layouts, data files, and includes are all placed in their default locations. Stylesheets and scripts in `assets`, and a few development related files in the root.
|
||||
|
||||
```bash
|
||||
minimal-mistakes
|
||||
|
|
|
|||
|
|
@ -11,33 +11,55 @@ sidebar:
|
|||
|
||||
## Install the Theme
|
||||
|
||||
There are several ways to install the theme.
|
||||
There are several ways to install the theme:
|
||||
|
||||
The easiest being: fork the Minimal Mistakes repo on GitHub. If you plan on hosting your site with GitHub Pages then following the steps outlined in the **Quick-Start Guide**.
|
||||
**1.** For a **new site**, fork the Minimal Mistakes repo on GitHub. If you plan on hosting your site with GitHub Pages follow the steps outlined in the *Quick-Start Guide*.
|
||||
|
||||
For an existing site you have some more work ahead of you. What I suggest is to fork and rename the theme as before, then clone it by running `git clone https://github.com/USERNAME/REPONAME.git` --- replacing **USERNAME** and **REPONAME** with yours.
|
||||
**2.** For an **existing site** you have some more work ahead of you. What I suggest is to fork and rename the theme's repo as before, then clone it locally by running `git clone https://github.com/USERNAME/REPONAME.git` --- replacing **USERNAME** and **REPONAME** with your own.
|
||||
|
||||
<figure>
|
||||
<img src="{{ base_path }}/images/mm-github-copy-repo-url.png" alt="copy GitHub repo URL">
|
||||
<figcaption>Tap the copy to clipboard button, outlined in red above.</figcaption>
|
||||
<figcaption>Tap the copy to clipboard button (outlined in red above) to grab your GitHub repo's path.</figcaption>
|
||||
</figure>
|
||||
|
||||
Then depending on how much existing content you're moving over begin the process of copying and converting everything. In most cases you simply need to update the settings in `_config.yml` to your liking and set the correct `layout` in the YAML Front Matter.
|
||||
|
||||
**Converting Existing Content**: Be sure to read through the "Working with Posts/Pages/Collections" documentation to learn about all the options available to you. Minimal Mistakes has been designed to be flexible, with numerous settings for toggling features on/off.
|
||||
{: .notice--info}
|
||||
|
||||
If for some chance you don't want to mess with Git you can also download the theme as a ZIP file and work with it locally that way.
|
||||
**3.** And for those who don't want to mess with Git, you can download the theme as a ZIP file to work with locally.
|
||||
|
||||
[Download Minimal Mistakes Theme](https://github.com/mmistakes/minimal-mistakes/archive/master.zip){: .btn .btn--success}
|
||||
|
||||
---
|
||||
|
||||
To move over any existing content you'll want to copy the contents of your `_posts` folder to the new site. Along with any pages, collections, data files, images, or other assets.
|
||||
|
||||
Next you'll need to convert posts and pages to use the proper layouts and settings. In most cases you simply need to update `_config.yml` to your liking and set the correct `layout` in their YAML Front Matter.
|
||||
|
||||
[**Front Matter defaults**](https://jekyllrb.com/docs/configuration/#front-matter-defaults) are your friend and I encourage you to leverage them instead of setting a layout and other global options in each post/page's YAML Front Matter.
|
||||
|
||||
With something like this in your `_config.yml` all posts can be assigned the `single` page layout with reading time, comments, social sharing links, and related posts enabled.
|
||||
|
||||
```yaml
|
||||
defaults:
|
||||
# _posts
|
||||
- scope:
|
||||
path: ""
|
||||
type: posts
|
||||
values:
|
||||
layout: single
|
||||
read_time: true
|
||||
comments: true
|
||||
share: true
|
||||
related: true
|
||||
```
|
||||
|
||||
**Post/Page Settings**: Be sure to read through the "Working with Posts/Pages/Collections" documentation to learn about all the options available to you. Minimal Mistakes has been designed to be flexible, with numerous settings for toggling features on/off.
|
||||
{: .notice--info}
|
||||
|
||||
## Install Dependencies
|
||||
|
||||
If this is your first time using Jekyll be sure to read through the [official documentation](https://jekyllrb.com/docs/home/) to familiarize yourself. This guide assumes you've done that and have Ruby v2 installed.
|
||||
|
||||
To keep your sanity and better manage dependencies I strongly urge you to [install Bundler](http://bundler.io/) with `gem install bundler` and use the included [`Gemfile`](https://github.com/mmistakes/minimal-mistakes/blob/master/Gemfile). Minimal Mistake's Gemfile defaults to the `github-pages` gem to maintain a local Jekyll environment in sync with GitHub Pages.
|
||||
|
||||
If you're not planning on hosting with GitHub Pages and want to leverage features found in the latest version of Jekyll replace `gem "github-pages"` with `gem "jekyll"` in `Gemfile` and then run:
|
||||
If you're not planning on hosting with GitHub Pages and want to leverage features found in the latest version of Jekyll replace `gem "github-pages"` with `gem "jekyll"` in your `Gemfile` and then run:
|
||||
|
||||
```bash
|
||||
$ bundle install
|
||||
|
|
@ -48,3 +70,7 @@ $ bundle install
|
|||
</figure>
|
||||
|
||||
Depending on what gems you already have installed you may have to run `bundle update` to clear up any dependency issues. Bundler is usually pretty good at letting you know what the issue is to work through them.
|
||||
|
||||
When using Bundler to manage gems you'll want to run Jekyll using `bundle exec jekyll serve` and `bundle exec jekyll build`. Essentially prepending any Jekyll command with `bundle exec`.
|
||||
|
||||
Doing so executes the gem versions specified in `Gemfile.lock`. Sure you can go cowboy and test your luck with a naked `jekyll serve`. A lot of Jekyll errors I see can be tracked down to gems fighting with each other. So do yourself a favor and just use Bundler.
|
||||
Loading…
Reference in a new issue