From d8be6fd2b54bc912fd0167cbce8213373ff60645 Mon Sep 17 00:00:00 2001 From: ashmaroli Date: Fri, 4 Aug 2017 22:07:08 +0530 Subject: [PATCH] Update documentation (#1151) * Update Quickstart documentation * update Installation documentation * Update documentation for Overriding Defaults --- docs/_docs/01-quick-start-guide.md | 18 +++++++++++++----- docs/_docs/03-installation.md | 17 ++++++++++------- docs/_docs/06-overriding-theme-defaults.md | 3 +++ 3 files changed, 26 insertions(+), 12 deletions(-) diff --git a/docs/_docs/01-quick-start-guide.md b/docs/_docs/01-quick-start-guide.md index 5bf2f6d2..e368b492 100644 --- a/docs/_docs/01-quick-start-guide.md +++ b/docs/_docs/01-quick-start-guide.md @@ -99,7 +99,10 @@ Depending on the path you took installing Minimal Mistakes you'll setup things a Starting with an empty folder and `Gemfile` you'll need to copy or re-create this [default `_config.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_config.yml) file. For a full explanation of every setting be sure to read the [**Configuration**]({{ "/docs/configuration/" | absolute_url }}) section. -After taking care of Jekyll's configuration file, you'll need to create and edit the following data files. +From `v4.5.0` onwards, Minimal Mistakes theme-gem comes bundled with the necessary data files and will automatically use them via the [`jekyll-data`](https://github.com/ashmaroli/jekyll-data) plugin. So you no longer need to maintain a copy of these data files at your project directory. + +However like all other bundled files, you'll need to create and edit these data files to customize them. +The bundled data files are: - [`_data/ui-text.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_data/ui-text.yml) - UI text [documentation]({{ "/docs/ui-text/" | absolute_url }}) - [`_data/navigation.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_data/navigation.yml) - navigation [documentation]({{ "/docs/navigation/" | absolute_url }}) @@ -108,7 +111,7 @@ After taking care of Jekyll's configuration file, you'll need to create and edit Scaffolding out a site with the `jekyll new` command requires you to modify a few files that it creates. -Edit `_config.yml` and create `_data/ui-text.yml` and `_data/navigation.yml` same as above. Then: +Edit `_config.yml`. Then: - Replace `/index.md` with a modified [Minimal Mistakes `index.html`](https://github.com/mmistakes/minimal-mistakes/blob/master/index.html). Be sure to enable pagination if using the [`home` layout]({{ "/docs/layouts/#home-page" | absolute_url }}) by adding the necessary lines to **_config.yml**. - Change `layout: post` in `_posts/0000-00-00-welcome-to-jekyll.markdown` to `layout: single`. @@ -118,13 +121,18 @@ Edit `_config.yml` and create `_data/ui-text.yml` and `_data/navigation.yml` sam If you're migrating a site already using Minimal Mistakes and haven't customized any of the theme files things upgrading will be easier for you. -Start by removing `_includes`, `_layouts`, `_sass`, `assets` folders and all files within. You won't need these anymore as they're bundled with the theme gem. +Start by removing `_includes`, `_layouts`, `_sass`, `assets` folders and all files within. + +You won't need these anymore as they're bundled with the theme gem. + +From `v4.5.0` onwards, you don't have to maintain a copy of the default data files viz. `_data/ui-text.yml` and `_data/navigation.yml` either. +The default files are read-in automatically via the [`jekyll-data`](https://github.com/ashmaroli/jekyll-data) plugin. If you customized any of these files leave them alone, and only remove the untouched ones. If done correctly your modified versions should [override](http://jekyllrb.com/docs/themes/#overriding-theme-defaults) the versions bundled with the theme and be used by Jekyll instead. #### Update Gemfile -Replace `gem "github-pages` or `gem "jekyll"` with `gem "jekyll", "~> 3.3.0"`. You'll need the latest version of Jekyll[^update-jekyll] for Minimal Mistakes to work and load all of the theme's assets properly, this line forces Bundler to do that. +Replace `gem "github-pages` or `gem "jekyll"` with `gem "jekyll", "~> 3.5"`. You'll need the latest version of Jekyll[^update-jekyll] for Minimal Mistakes to work and load all of the theme's assets properly, this line forces Bundler to do that. [^update-jekyll]: You could also run `bundle update jekyll` to update Jekyll. @@ -139,7 +147,7 @@ When finished your `Gemfile` should look something like this: ```ruby source "https://rubygems.org" -gem "jekyll", "~> 3.3.0" +gem "jekyll", "~> 3.5" gem "minimal-mistakes-jekyll" ``` diff --git a/docs/_docs/03-installation.md b/docs/_docs/03-installation.md index 549238a4..ad59ef79 100644 --- a/docs/_docs/03-installation.md +++ b/docs/_docs/03-installation.md @@ -74,16 +74,19 @@ source "https://rubygems.org" # To upgrade, run `bundle update`. -gem "jekyll", "~> 3.3.0" +gem "jekyll", "~> 3.5" gem "minimal-mistakes-jekyll" -# If you have any plugins, put them here! +# The following plugins are automatically loaded by the theme-gem: +# gem "jekyll-paginate" +# gem "jekyll-sitemap" +# gem "jekyll-gist" +# gem "jekyll-feed" +# gem "jemoji" +# gem "jekyll-data" +# +# If you have any other plugins, put them here! group :jekyll_plugins do - gem "jekyll-paginate" - gem "jekyll-sitemap" - gem "jekyll-gist" - gem "jekyll-feed" - gem "jemoji" end ``` diff --git a/docs/_docs/06-overriding-theme-defaults.md b/docs/_docs/06-overriding-theme-defaults.md index 17329112..c6f8468f 100644 --- a/docs/_docs/06-overriding-theme-defaults.md +++ b/docs/_docs/06-overriding-theme-defaults.md @@ -21,4 +21,7 @@ Jekyll will use the files in your project first before falling back to the defau /_sass ``` +Additionally, from `v4.5.0` the theme-gem will also exhibit above behavior for `/_data` via a plugin. +Consequently, the data files for UI Text and Navigation are also bundled within the theme-gem. + For more information on customizing the theme's [stylesheets]({{ "/docs/stylesheets/" | absolute_url }}) and [JavaScript]({{ "/docs/javascript/" | absolute_url }}), see the appropriate pages. \ No newline at end of file