Reorder docs navigation
This commit is contained in:
Michael Rose
parent
0af17256f6
commit
f7a4710330
6 changed files with 143 additions and 61 deletions
|
|
@ -25,12 +25,12 @@ docs:
|
||||||
children:
|
children:
|
||||||
- title: "Quick-Start Guide"
|
- title: "Quick-Start Guide"
|
||||||
path: quick-start-guide
|
path: quick-start-guide
|
||||||
|
- title: "Structure"
|
||||||
|
path: structure
|
||||||
- title: "Installation"
|
- title: "Installation"
|
||||||
path: installation
|
path: installation
|
||||||
- title: "Upgrading"
|
- title: "Upgrading"
|
||||||
path: upgrading
|
path: upgrading
|
||||||
- title: "Structure"
|
|
||||||
path: structure
|
|
||||||
|
|
||||||
- title: Customization
|
- title: Customization
|
||||||
children:
|
children:
|
||||||
|
|
@ -58,7 +58,7 @@ docs:
|
||||||
- title: "Images"
|
- title: "Images"
|
||||||
path: images
|
path: images
|
||||||
|
|
||||||
- title: Miscellaneous
|
- title: Extras
|
||||||
children:
|
children:
|
||||||
- title: "Pagination"
|
- title: "Pagination"
|
||||||
path: pagination
|
path: pagination
|
||||||
|
|
|
||||||
|
|
@ -7,13 +7,31 @@ sidebar:
|
||||||
---
|
---
|
||||||
|
|
||||||
{% include base_path %}
|
{% 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**
|
## Fork the Theme
|
||||||
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.
|
|
||||||
|
|
||||||
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/).
|
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.
|
||||||
{: .notice--info}
|
|
||||||
|
**<< 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.
|
||||||
|
|
@ -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
55
_docs/02-structure.md
Normal 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
45
_docs/03-installation.md
Normal 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
15
_docs/04-upgrading.md
Normal 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
|
||||||
Loading…
Reference in a new issue