Edit theme documentation.

This commit is contained in:
Michael Rose 2013-06-06 11:51:01 -04:00
parent 8f71c3ddd3
commit 283f529687

View file

@ -54,13 +54,13 @@ minimal-mistakes/
### _config.yml ### _config.yml
Most of the variables found here are used in the .html files found in *_includes* if you need to add or remove anything. A good place to start would be to change the title, tagline, description, and url of your site. When working locally comment out `url` or else you will get a bunch of broken links because they are absolute and prefixed with `{{ site.url }}` in the various `_includes` and `_layouts`. Just remember to uncomment `url` when building for deployment or pushing to **gh-pages**... Most of the variables found here are used in the .html files found in `_includes` if you need to add or remove anything. A good place to start would be to change the title, tagline, description, and url of your site. When working locally comment out `url` or else you will get a bunch of broken links because they are absolute and prefixed with `{{ site.url }}` in the various `_includes` and `_layouts`. Just remember to uncomment `url` when building for deployment or pushing to **gh-pages**...
#### Owner/Author Information #### Owner/Author Information
Change your name, bio, and avatar photo (100x100 pixels or larger), Twitter url, email, and Google+ url. If you want to link to an external image on Gravatar or something similiar you'll need to edit the path in `author-bio.html` since it assumes it is located in \images. Change your name, bio, and avatar photo (100x100 pixels or larger), Twitter url, email, and Google+ url. If you want to link to an external image on Gravatar or something similiar you'll need to edit the path in `author-bio.html` since it assumes it is located in `\images`.
Including a link to your Google+ profile has the added benefit of displaying [Google Authorship](https://plus.google.com/authorship) if you've went ahead and applied for it. Don't have a Google+ account? Just leave it blank and/or remove `<link rel="author" href="{{ site.owner.google_plus }}">` from `head.html`. Including a link to your Google+ profile has the added benefit of displaying [Google Authorship](https://plus.google.com/authorship) in Google search results if you've went ahead and applied for it. Don't have a Google+ account? Just leave it blank and/or remove `<link rel="author" href="{{ site.owner.google_plus }}">` from `head.html`.
#### Google Analytics and Webmaster Tools #### Google Analytics and Webmaster Tools
@ -70,17 +70,28 @@ Your Google Analytics ID goes here along with meta tags for [Google Webmaster To
Edit page/post titles and URLs to include in the site's navigation. If you want to add links to other sites you can hardcode them into `navigation.html`. Edit page/post titles and URLs to include in the site's navigation. If you want to add links to other sites you can hardcode them into `navigation.html`.
``` yaml
# sample top navigation links
links:
- title: About Page
url: /about
- title: Articles
url: /articles
- title: Other Page
url: /other-page
```
#### Other Stuff #### Other Stuff
The rest is just your average Jekyll config settings. Nothing too crazy here... The rest is just your average Jekyll config settings. Nothing too crazy here...
### _includes ### _includes
For the most part you can leave these as is since the author/owner details are pulled from `_config.yml`. That said you'll probably want to customize the page links in `navigation.html` and copyright stuff in `footer.html` to your liking. For the most part you can leave these as is since the author/owner details are pulled from `_config.yml`. That said you'll probably want to customize the copyright stuff in `footer.html` to your liking.
### Adding Posts and Pages ### Adding Posts and Pages
There are two main content layouts: *post.html* (for posts) and *page.html* (for pages). Both have large **feature images** that span the full-width of the screen, and both are meant for text heavy blog posts (or articles). There are two main content layouts: `post.html` (for posts) and `page.html` (for pages). Both have large **feature images** that span the full-width of the screen, and both are meant for text heavy blog posts (or articles).
#### Feature Images #### Feature Images
@ -100,19 +111,19 @@ The large texture images used in *Minimal Mistakes* are from [Love Textures](htt
In the sample `_posts` folder you may have noticed `category: articles` in the front matter. I like keeping all posts grouped in the same folder. If you decide to rename or add categories you will need to modify the permalink in `articles.md` along with the filename (if renaming). In the sample `_posts` folder you may have noticed `category: articles` in the front matter. I like keeping all posts grouped in the same folder. If you decide to rename or add categories you will need to modify the permalink in `articles.md` along with the filename (if renaming).
For example. Say you want to group all your posts under **blog** instead of articles. In your post add `category: blog` to the front matter, rename or duplicate `articles.md` to `blog.md` and change the permalink in that file to `permalink: /blog/index.html`. For example. Say you want to group all your posts under `blog/` instead of `articles/`. In your post add `category: blog` to the front matter, rename or duplicate `articles.md` to `blog.md` and change the permalink in that file to `permalink: /blog/index.html`.
If done correctly `/blog` should be a page listing all posts. If done correctly `/blog` should be a page listing all the site's posts.
#### Thumbnails for OG and Twitter Cards #### Thumbnails for OG and Twitter Cards
Post and page thumbnails work the same way. These are used by [Open Graph](https://developers.facebook.com/docs/opengraph/) and [Twitter Cards](https://dev.twitter.com/docs/cards) meta tags found in *head.html*. If you don't assign a thumbnail the default graphic *(default-thumb.png)* is used. I'd suggest changing this to something more meaningful --- your logo or avatar are good options. Post and page thumbnails work the same way. These are used by [Open Graph](https://developers.facebook.com/docs/opengraph/) and [Twitter Cards](https://dev.twitter.com/docs/cards) meta tags found in `head.html`. If you don't assign a thumbnail the default graphic *(default-thumb.png)* is used. I'd suggest changing this to something more meaningful -- your logo or avatar are good options.
#### Table of Contents #### Table of Contents
Any article or page that you want a *table of contents* to render insert the following HTML in your post before the actual content. [Kramdown will take care of the rest](http://kramdown.rubyforge.org/converter/html.html#toc) and convert all headlines into a contents list. Insert the following HTML in post or page content that you want a *table of contents* to render. [Kramdown will take care of the rest](http://kramdown.rubyforge.org/converter/html.html#toc) and convert all headlines into a contents list.
**PS:** The TOC is hidden on small devices because I haven't gotten around to optimizing it. For now it only shows on tablets and desktop viewports... **PS:** The TOC is hidden on small devices because I haven't gotten around to optimizing it. For now it only shows on tablet and desktop breakpoints...
``` html ``` html
<section id="table-of-contents" class="toc"> <section id="table-of-contents" class="toc">
@ -140,6 +151,10 @@ Not sure if this only effects Kramdown or if it's an issue with Markdown in gene
Twitter cards make it possible to attach images and post summaries to Tweets that link to your content. Summary Card meta tags have been added to `head.html` to support this, you just need to [validate and apply your domain](https://dev.twitter.com/docs/cards) to turn it on. Twitter cards make it possible to attach images and post summaries to Tweets that link to your content. Summary Card meta tags have been added to `head.html` to support this, you just need to [validate and apply your domain](https://dev.twitter.com/docs/cards) to turn it on.
## Questions?
Having a problem getting something to work or want to know why I setup something in a certain way? Ping me on Twitter [@mmistakes](http://twitter.com/mmistakes) or [file a GitHub Issue](https://github.com/mmistakes/minimal-mistakes/issues/new).
## License ## License
This is [MIT](LICENSE) with no added caveats, so feel free to use this Jekyll theme on your site without linking back to me or using a disclaimer. This is [MIT](LICENSE) with no added caveats, so feel free to use this Jekyll theme on your site without linking back to me or using a disclaimer.