From c1d8c79152cade2fb75904c9d0c235d59eafa6e2 Mon Sep 17 00:00:00 2001 From: Michael Rose Date: Tue, 5 Apr 2016 16:55:13 -0400 Subject: [PATCH] Update docs --- _docs/01-quick-start-guide.md | 2 +- _docs/02-structure.md | 2 +- _docs/03-installation.md | 48 +++++++++++++++++++++++++++-------- 3 files changed, 39 insertions(+), 13 deletions(-) diff --git a/_docs/01-quick-start-guide.md b/_docs/01-quick-start-guide.md index 6ae4819..29e2251 100644 --- a/_docs/01-quick-start-guide.md +++ b/_docs/01-quick-start-guide.md @@ -19,7 +19,7 @@ Fork the [Minimal Mistakes theme](https://github.com/mmistakes/minimal-mistakes/ fork Minimal Mistakes -Your Jekyll site should be viewable immediately at . 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 . 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/). diff --git a/_docs/02-structure.md b/_docs/02-structure.md index b29b94b..369f3bf 100644 --- a/_docs/02-structure.md +++ b/_docs/02-structure.md @@ -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 diff --git a/_docs/03-installation.md b/_docs/03-installation.md index 4275db5..3e03e87 100644 --- a/_docs/03-installation.md +++ b/_docs/03-installation.md @@ -11,25 +11,47 @@ 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.
copy GitHub repo URL -
Tap the copy to clipboard button, outlined in red above.
+
Tap the copy to clipboard button (outlined in red above) to grab your GitHub repo's path.
-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. +**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. -**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} +[Download Minimal Mistakes Theme](https://github.com/mmistakes/minimal-mistakes/archive/master.zip){: .btn .btn--success} -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. +--- -[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 @@ -37,7 +59,7 @@ If this is your first time using Jekyll be sure to read through the [official do 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 @@ -47,4 +69,8 @@ $ bundle install bundle install in Terminal window -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. \ No newline at end of file +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. \ No newline at end of file -- 2.43.0