Reorder docs navigation

This commit is contained in:
Michael Rose 2016-04-04 16:36:26 -04:00
parent 0af17256f6
commit f7a4710330
6 changed files with 143 additions and 61 deletions

View file

@ -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

View file

@ -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}
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 <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/).
**<< 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 <USERNAME.github.io>.
---
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.

View file

@ -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 <http://yourgithubusername.github.io> --- 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

55
_docs/02-structure.md Normal file
View file

@ -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
```

45
_docs/03-installation.md Normal file
View file

@ -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.

15
_docs/04-upgrading.md Normal file
View file

@ -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