From f7a47103301e44cfc45f1b40cf6df18d096308f0 Mon Sep 17 00:00:00 2001 From: Michael Rose Date: Mon, 4 Apr 2016 16:36:26 -0400 Subject: [PATCH] Reorder docs navigation --- _data/navigation.yml | 6 ++-- _docs/01-quick-start-guide.md | 32 +++++++++++++++----- _docs/02-installation.md | 51 -------------------------------- _docs/02-structure.md | 55 +++++++++++++++++++++++++++++++++++ _docs/03-installation.md | 45 ++++++++++++++++++++++++++++ _docs/04-upgrading.md | 15 ++++++++++ 6 files changed, 143 insertions(+), 61 deletions(-) delete mode 100644 _docs/02-installation.md create mode 100644 _docs/02-structure.md create mode 100644 _docs/03-installation.md create mode 100644 _docs/04-upgrading.md diff --git a/_data/navigation.yml b/_data/navigation.yml index dfae6d4..710fe4e 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -25,12 +25,12 @@ docs: children: - title: "Quick-Start Guide" path: quick-start-guide + - title: "Structure" + path: structure - title: "Installation" path: installation - title: "Upgrading" path: upgrading - - title: "Structure" - path: structure - title: Customization children: @@ -58,7 +58,7 @@ docs: - title: "Images" path: images - - title: Miscellaneous + - title: Extras children: - title: "Pagination" path: pagination diff --git a/_docs/01-quick-start-guide.md b/_docs/01-quick-start-guide.md index 9056970..fa77ab7 100644 --- a/_docs/01-quick-start-guide.md +++ b/_docs/01-quick-start-guide.md @@ -7,13 +7,31 @@ sidebar: --- {% include base_path %} +{% include toc %} -Minimal Mistakes has been developed to be 100% compatible with GitHub Pages hosting. To get up and running with a new GitHub repository following these steps. +Minimal Mistakes has been developed to be 100% compatible with hosting a site on [GitHub Pages](https://pages.github.com/). To get up and running with a new GitHub repository quickly, follow these steps. -1. Fork the [Minimal Mistakes theme](https://github.com/mmistakes/minimal-mistakes/fork) and then rename the repo to **_USERNAME_.github.io** -2. Clone your new repo with `git clone https://github.com/USERNAME/REPONAME.git` -3. [Install Bundler](http://bundler.io) and theme dependencies with `bundle install`. -4. Customize configuration, data files, and publish your first post. +## Fork the Theme -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 **yourgithubusername.github.io** and use the `gh-pages` branch instead of `master`. For more details check [GitHub's documentation](https://help.github.com/articles/user-organization-and-project-pages/). -{: .notice--info} \ No newline at end of file +Fork the [Minimal Mistakes theme](https://github.com/mmistakes/minimal-mistakes/fork), then rename the repo to **USERNAME.github.io** --- replacing **USERNAME** with your GitHub username. + +**<< insert animation showing how to fork GitHub repo >>** + +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/). + +**<< insert animation showing how create to gh-pages branch >>** + +## Customize Your Site + +Open up `_config.yml` found in the root of the repo and edit anything under **Site Settings**. For a full explanation of every setting be sure to read the **Customization** section, but for now let's just change the site's title. + +**<< insert animation showing how to edit the site title >>** + +Committing a change to `_config.yml` (or any file in your repository) will force GitHub Pages to rebuild your site with Jekyll. It should then be viewable a few seconds later at . + +--- + +Congratulations! You've successfully forked the Minimal Mistakes Jekyll theme and are up an running with GitHub Pages. Now you're ready to add some content and customize the site further. \ No newline at end of file diff --git a/_docs/02-installation.md b/_docs/02-installation.md deleted file mode 100644 index 57e5a64..0000000 --- a/_docs/02-installation.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Installation" -permalink: /docs/installation/ -excerpt: -sidebar: - nav: docs ---- - -{% include base_path %} -{% include toc %} - -Minimal Mistakes has been developed to be 100% compatible with sites hosted on GitHub Pages. To get up and running with a new GitHub repository following these steps. - -## Fork Minimal Mistakes - -[Fork this repo](https://github.com/mmistakes/minimal-mistakes/fork), then rename it to **_yourgithubusername_.github.io** - -Your Jekyll based site should then be viewable at --- if it's not, you can force it to build by adding and publishing your a post (see below). - -## 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). - -```bash -$ bundle install -``` - -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. - -## Customize Your Site - -Enter your site name, description, avatar and many other options by editing the _config.yml file. You can easily turn on Google Analytics tracking, Disqus commenting and social icons here too. - -Making a change to _config.yml (or any file in your repository) will force GitHub Pages to rebuild your site with jekyll. Your rebuilt site will be viewable a few seconds later at http://yourgithubusername.github.io - if not, give it ten minutes as GitHub suggests and it'll appear soon - -There are 3 different ways that you can make changes to your blog's files: - -Edit files within your new username.github.io repository in the browser at GitHub.com (shown below). -Use a third party GitHub content editor, like Prose by Development Seed. It's optimized for use with Jekyll making markdown editing, writing drafts, and uploading images really easy. -Clone down your repository and make updates locally, then push them to your GitHub repository. -_config.yml - -Step 3) Publish your first blog post - -Edit /_posts/2014-3-3-Hello-World.md to publish your first blog post. This Markdown Cheatsheet might come in handy. - -First Post - -You can add additional posts in the browser on GitHub.com too! Just hit the + icon in /_posts/ to create new content. Just make sure to include the front-matter block at the top of each new blog post and make sure the post's filename is in this format: year-month-day-title.md \ No newline at end of file diff --git a/_docs/02-structure.md b/_docs/02-structure.md new file mode 100644 index 0000000..6095093 --- /dev/null +++ b/_docs/02-structure.md @@ -0,0 +1,55 @@ +--- +title: "Structure" +permalink: /docs/structure/ +excerpt: +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:. + +```bash +minimal-mistakes +├── _data +| ├── navigations.yml +| └── ui-text.yml +├── _includes +| ├── analytics-providers +| ├── comments-providers +| ├── footer +| ├── head +| ├── base_path +| ├── feature-row +| ├── gallery +| ├── group-by-array +| ├── nav_list +| ├── toc +| └── ... +├── _layouts +| ├── archive-taxonomy.html +| ├── archive.html +| ├── compress.html +| ├── default.html +| ├── single.html +| └── splash.html +├── assets +| ├── _scss +| | ├── vendor +| | ├── main.scss +| | └── ... +| ├── css +| | └── main.css +| ├── fonts +| | └── fontawesome-webfont +| ├── js +| | ├── plugins +| | ├── vendor +| | ├── _main.js +| | └── main.min.js +├── assets +├── _config.yml +├── Gemfile +├── Gemfile.lock +├── index.html +└── package.json +``` \ No newline at end of file diff --git a/_docs/03-installation.md b/_docs/03-installation.md new file mode 100644 index 0000000..63f9667 --- /dev/null +++ b/_docs/03-installation.md @@ -0,0 +1,45 @@ +--- +title: "Installation" +permalink: /docs/installation/ +excerpt: +sidebar: + nav: docs +--- + +{% include base_path %} +{% include toc %} + +## 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**. + +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. + +**<< insert screenshot showing where to copy the repo's URL on GitHub >>** + +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. + +[Download Minimal Mistakes Theme](https://github.com/mmistakes/minimal-mistakes/archive/master.zip){: .btn .btn--success} + +## 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: + +```bash +$ bundle install +``` + +**<< insert screenshot of Terminal running bundle install >>** + +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 diff --git a/_docs/04-upgrading.md b/_docs/04-upgrading.md new file mode 100644 index 0000000..9a497f7 --- /dev/null +++ b/_docs/04-upgrading.md @@ -0,0 +1,15 @@ +--- +title: "Upgrading" +permalink: /docs/upgrading/ +excerpt: +sidebar: + nav: docs +--- + +{% include base_path %} + +Currently there is no good way of upgrading the theme without doing some manual work. The future looks promising with [**gem based themes**](https://github.com/jekyll/jekyll/pull/4595) on the horizon, but for now here's some suggestions on how handle theme updates. + +## Use Git + +## Download ZIP, Update Files Manually \ No newline at end of file -- 2.43.0