Prepare 0.1.3 release

CHANGELOG

@@ -1,3 +1,10 @@
+mkdocs-material-0.1.3 (2016-02-21)
+
+  * Fixed #3: Ordered lists within an unordered list have ::before content
+  * Fixed #4: Click on Logo/Title without Github-Repository: "None"
+  * Fixed #5: Page without headlines renders empty list in table of contents
+  * Moved Modernizr to top to ensure basic usability in IE8
+
 mkdocs-material-0.1.2 (2016-02-16)
 
   * Fixed styles for deep navigational hierarchies

README.md

@@ -27,7 +27,8 @@ http://squidfunk.github.io/mkdocs-material/
 
 ## License
 
-**MIT License**  
+**MIT License**
+
 Copyright (c) 2016 Martin Donath
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

bower.json

@@ -1,6 +1,6 @@
 {
   "name": "mkdocs-material",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A material design theme for MkDocs",
   "homepage": "http://squidfunk.github.io/mkdocs-material/",
   "authors": [

docs/customization.md

@@ -26,23 +26,28 @@ Further assistance on including extra CSS and Javascript can be found in the
 ## Fundamental changes
 
 If you want to make larger adjustments like changing the color palette or
-typography, you should check out the repository of the project and compile
-the SASS sources with your changes. The project design is very modular, so
-most things can be changed by tweaking a few variables.
+typography, you should check out or download the repository of the project and
+compile the SASS sources with your changes. The project design is very modular,
+so most things can be tweaked by changing a few variables.
 
 ### Setup
 
-In order to compile the project, you need `node`, `bower` and `gulp` up and
-running. It's best to use the most recent versions, but it should also work if
-your installations are not too dated. The project itself is hosted on GitHub,
-so the next thing you should do is clone the project from GitHub:
+In order to compile the project, you need `node` with a version greater than
+`0.11` up and running. Then, make sure `bower` is installed or install it:
+
+``` sh
+npm install -g bower
+```
+
+The project itself is hosted on GitHub, so the next
+thing you should do is clone the project from GitHub:
 
 ``` sh
 git clone https://github.com/squidfunk/mkdocs-material
 ```
 
 Then you change the directory and install all dependencies specified in the
-`package.json` and `bower.json`:
+`package.json` and `bower.json` with the following command:
 
 ``` sh
 cd mkdocs-material
@@ -52,12 +57,12 @@ npm install && bower install
 ### Development
 
 The asset pipeline is contained in `Gulpfile.js`, which you can start with
-`gulp watch`. This will also run `mkdocs serve`, to monitor changes to the
-documentation. Point your browser to [localhost:8000](http://localhost:8000)
-and you should see this very documentation in front of your eyes.
+`gulp watch`. If you specify the `--mkdocs` flag, this will also run
+`mkdocs serve`, to monitor changes to the documentation. Point your browser to [localhost:8000](http://localhost:8000) and you should see this very
+documentation in front of your eyes.
 
 ``` sh
-gulp watch
+gulp watch --mkdocs
 ```
 
 For example, changing the color palette is as simple as changing the `$primary`
@@ -80,11 +85,18 @@ When you finished making your changes, you can build the theme by invoking:
 gulp build --production
 ```
 
-The `production` flag triggers the production-level compilation and
+The `--production` flag triggers the production-level compilation and
 minification of all CSS and Javascript sources. When the command is ready,
 the final theme is located in the `material` directory. Add the `theme_dir`
 variable pointing to the aforementioned directory in your original
-`mkdocs.yml` and you should see your documentation with your changes!
+`mkdocs.yml`:
+
+``` yaml
+theme_dir: 'mkdocs-material/material'
+```
+
+Now you can run `mkdocs build` and you should see your documentation with your
+changes to the original Material theme.
 
 [MkDocs]: http://www.mkdocs.org
 [MkDocs documentation]: http://www.mkdocs.org/user-guide/styling-your-docs/#customising-a-theme

docs/getting-started.md

@@ -4,7 +4,7 @@
 
 ### Installing MkDocs
 
-In order to install [MkDocs][], Python and `pip` - the Python package manager -
+In order to install [MkDocs][], Python and `pip` – the Python package manager –
 need to be up and running. Assuming you are a developer and have a basic
 understanding of how things work and what StackOverflow is, we won't provide
 guidelines on setting those up. You can verify if you're already good to go
@@ -76,19 +76,6 @@ on and customize the theme through some options.
 The Material theme adds some extra variables for configuration via your
 project's `mkdocs.yml`. See the following section for all available options.
 
-### Adding a logo
-
-If your project has a logo, you can add it to the drawer/navigation by defining
-the variable `extra.logo`. Ideally, the image of your logo should have
-rectangular shape with a minimum resolution of 128x128. The logo will also be
-used as a web application icon on iOS. Simply create the folder `docs/images`,
-add your image and reference it via:
-
-``` yaml
-extra:
-  logo: 'images/logo.png'
-```
-
 ### Adding a version
 
 In order to add the current version next to the project banner inside the
@@ -99,6 +86,46 @@ extra:
   version: '0.1.0'
 ```
 
+This will also change the link behind the download button to point to the
+archive with the respective version on GitHub, assuming a release tagged with
+this exact version identifier.
+
+### Adding a logo
+
+If your project has a logo, you can add it to the drawer/navigation by defining
+the variable `extra.logo`. Ideally, the image of your logo should have
+rectangular shape with a minimum resolution of 128x128 and leave some room
+towards the edges. The logo will also be used as a web application icon on iOS.
+Simply create the folder `docs/images`, add your image and reference it via:
+
+``` yaml
+extra:
+  logo: 'images/logo.png'
+```
+
+### Changing the font family
+
+Material uses the [Ubuntu font family][] by default, specifically the regular
+sans-serif type for text and the monospaced type for code. Both fonts are
+loaded from [Google Fonts][] and can be easily changed to other fonts, like for
+example Google's own [Roboto font][]:
+
+``` yaml
+extra:
+  font:
+    text: 'Roboto'
+    code: 'Roboto Mono'
+```
+
+The text font will be loaded in font-weights 400 and 700, the monospaced font
+in regular weight. If you want to load fonts from other destinations or don't
+want to use the Google Fonts loading magic, just set `extra.font` to `'none'`:
+
+``` yaml
+extra:
+  font: 'none'
+```
+
 ### Adding a GitHub and Twitter account
 
 If you have a GitHub and/or Twitter account, you can add links to your
@@ -114,9 +141,8 @@ extra:
 
 ### More advanced customization
 
-If you want to change the fonts or colors - you are lucky. The Material theme
-is built with a sophisticated asset pipeline. See
-[this article](customization.md) for more information on advanced
+If you want to change the colors or general appearance of the Material theme,
+see [this article](customization.md) for more information on advanced
 customization.
 
 ## Extensions
@@ -170,16 +196,23 @@ In order to add a note, use the following syntax inside your article:
     Nothing to see here, move along.
 ```
 
-This will print the following:
+This will print the following block:
 
 !!! note
     Nothing to see here, move along.
 
 The Material template adds a neutral color for the `note` class and a red color
-for the `warning` class.
+for the `warning` class. You can also add a custom title:
 
-!!! warning
-    You shall not pass.
+``` markdown
+!!! warning "Don't try this at home"
+    If you do, you will regret it.
+```
+
+This will print:
+
+!!! warning "Don't try this at home"
+    If you do, you will regret it.
 
 More colors can be freely defined.
 
@@ -209,6 +242,9 @@ theme: 'material'
 extra:
   version: '0.1.0'
   logo: 'images/logo.png'
+  font:
+    text: 'Roboto'
+    code: 'Roboto Mono'
   author:
     github: 'my-github-handle'
     twitter: 'my-twitter-handle'
@@ -222,8 +258,11 @@ markdown_extensions:
 ```
 
 [MkDocs]: http://www.mkdocs.org
+[Ubuntu font family]: http://font.ubuntu.com
+[Google Fonts]: https://www.google.com/fonts
+[Roboto font]: https://www.google.com/fonts/specimen/Roboto
 [Markdown extensions]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
-[highlight.js]: https://highlightjs.org/
+[highlight.js]: https://highlightjs.org
 [extra]: http://www.mkdocs.org/user-guide/styling-your-docs/#customising-a-theme
 [permalinks]: https://en.wikipedia.org/wiki/Permalink
 [Admonition]: https://pythonhosted.org/Markdown/extensions/admonition.html

docs/index.md

@@ -2,46 +2,49 @@
 
 ## Beautiful documentation
 
-You're currently looking at a full responsive [MkDocs][] theme in the spirit of
-Google's [material design][] guidelines. MkDocs is an excellent static site
-documentation generator that is meant for building good looking project
-documentation.
+Material is a theme for [MkDocs][], an excellent static site generator geared
+towards project documentation. It is built using Google's [material design][]
+guidelines, full responsive, optimized for touch and pointer devices as well
+as all sorts of screen sizes.
 
 ![Material Screenshot](images/screen.png)
 
-This theme is **optimized for all sorts of devices** and is built from scratch
-without any bloated Javascript or CSS Frameworks with **only 24kb of JS and
-CSS** (minified, gzipped and excluding Google WebFonts and Analytics). Yet, it
-is highly customizable in terms of fonts, colors and gracefully supports older
+Material is very lightweight – it is built from scratch using Javascript and
+CSS that weighs less than 30kb (minified, gzipped and excluding Google Fonts
+and Analytics). Yet, it is highly customizable and degrades gracefully in older
 browsers.
 
 ## Features
 
-- Beautiful, readable and very user-friendly design based on Google's
-  **material design** guidelines, packed in a **full responsive** template
-  with a well-defined color palette, great typography, as well as a beautiful
-  search interface and footer.
+- Beautiful, readable and very user-friendly design based on Google's material
+  design guidelines, packed in a full responsive template with a well-defined
+  color palette, great typography, as well as a beautiful search interface and
+  footer.
 
-- Well-tested and **optimized CSS and Javascript**, including a cross-browser
+- Well-tested and optimized Javascript and CSS including a cross-browser
   fixed/sticky header, a drawer that even works without Javascript using
-  the `:checked` hack with fallbacks, **responsive tables** that scroll when
-  the screen is too small and **well-defined print styles**.
+  the [checkbox hack][] with fallbacks, responsive tables that scroll when
+  the screen is too small and well-defined print styles.
 
-- Extra configuration options like **project logo**, links to the authors
-  **GitHub and Twitter accounts** and display of the **amount of stars** the
+- Extra configuration options like a [project logo][], links to the authors
+  [GitHub and Twitter accounts][] and display of the amount of stars the
   project has on GitHub.
 
-- **Easily extendable and customizable** due to a well-designed asset pipeline
+- Easily [extendable and customizable][] due to a well-designed asset pipeline
   built on-top of [Gulp][] with `npm` and `bower` and modular and abstracted
   style definitions built with [SASS][].
 
-- **Web application capability** on iOS - when the page is saved to the
-  homescreen, it behaves and looks like a native application.
+- Web application capability on iOS - when the page is saved to the homescreen,
+  it behaves and looks like a native application.
 
 See the [getting started guide](getting-started.md) for instructions how to get
 it up and running.
 
-[material design]: https://www.google.com/design/spec/material-design
 [MkDocs]: http://www.mkdocs.org
+[material design]: https://www.google.com/design/spec/material-design
+[checkbox hack]: http://tutorialzine.com/2015/08/quick-tip-css-only-dropdowns-with-the-checkbox-hack/
+[project logo]: getting-started.md#adding-a-logo
+[GitHub and Twitter accounts]: getting-started.md#adding-a-github-and-twitter-account
+[extendable and customizable]: customization.md
 [Gulp]: http://gulpjs.com
-[SASS]: http://sass-lang.com/
+[SASS]: http://sass-lang.com

docs/license.md

@@ -1,6 +1,7 @@
 # License
 
-**MIT License**  
+**MIT License**
+
 Copyright (c) 2016 Martin Donath
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

material/base.html

@@ -53,7 +53,7 @@
       	font-style: normal;
       }
     </style>
-    <link rel="stylesheet" href="{{ base_url }}/assets/stylesheets/application-f5ffeca01e.css">
+    <link rel="stylesheet" href="{{ base_url }}/assets/stylesheets/application-eaf860cca2.css">
     {% if config.extra.font != 'none' %}
       {% set text = 'Ubuntu' %}
       {% if config.extra.font and config.extra.font.text %}
@@ -63,7 +63,7 @@
       {% if config.extra.font and config.extra.font.code %}
         {% set code = config.extra.font.code %}
       {% endif %}
-      {% set font = text + ':400,700|' + code | replace('+', ' ') %}
+      {% set font = text + ':400,700|' + code | replace(' ', '+') %}
       <link rel="stylesheet" href="//fonts.googleapis.com/css?family={{ font }}">
       <style>
         body, input {
@@ -77,10 +77,11 @@
     {% for path in extra_css %}
       <link rel="stylesheet" href="{{ path }}">
     {% endfor %}
+    <script src="{{ base_url }}/assets/javascripts/modernizr-4ab42b99fd.js"></script>
     {% block extrahead %}{% endblock %}
   </head>
   <body>
-    {% if repo_name == 'GitHub' %}
+    {% if repo_name == 'GitHub' and repo_url %}
       {% set repo_id = repo_url | replace('https://github.com/', '') %}
       {% if repo_id[-1:] == '/' %}
         {% set repo_id = repo_id[:-1] %}
@@ -137,12 +138,11 @@
         </div>
       </div>
     </main>
-    <script src="{{ base_url }}/assets/javascripts/modernizr-4ab42b99fd.js"></script>
     <script>
       var base_url = '{{ base_url }}';
       var repo_id  = '{{ repo_id }}';
     </script>
-    <script src="{{ base_url }}/assets/javascripts/application-c6d2e828bd.js"></script>
+    <script src="{{ base_url }}/assets/javascripts/application-a10a824a49.js"></script>
     {% for path in extra_javascript %}
       <script src="{{ path }}"></script>
     {% endfor %}

material/drawer.html

@@ -1,5 +1,6 @@
 <nav aria-label="Navigation">
-  <a href="{{ repo_url }}" class="project">
+  {% set home = repo_url | default('/', true) %}
+  <a href="{{ home }}" class="project">
     <div class="banner">
       {% if config.extra.logo %}
         <div class="logo">
@@ -17,7 +18,7 @@
   </a>
   <div class="scrollable">
     <div class="wrapper">
-      {% if repo_name == 'GitHub' %}
+      {% if repo_name == 'GitHub' and repo_url %}
         <ul class="repo">
           <li class="repo-download">
             {% set version = config.extra.version | default('master') %}

material/manifest.json

@@ -1,6 +1,6 @@
 {
   "assets/images/favicon.ico": "assets/images/favicon-e565ddfa3b.ico",
-  "assets/javascripts/application.js": "assets/javascripts/application-c6d2e828bd.js",
+  "assets/javascripts/application.js": "assets/javascripts/application-a10a824a49.js",
   "assets/javascripts/modernizr.js": "assets/javascripts/modernizr-4ab42b99fd.js",
-  "assets/stylesheets/application.css": "assets/stylesheets/application-f5ffeca01e.css"
+  "assets/stylesheets/application.css": "assets/stylesheets/application-eaf860cca2.css"
 }

material/nav.html

@@ -13,25 +13,21 @@
       {{ nav_item.title }}
     </a>
     {% if nav_item == current_page %}
-      <ul>
-        {% for toc_item in toc %}
-          {% if h1 %}
-            {% for toc_item in toc_item.children %}
-              <li class="anchor">
-                <a title="{{ toc_item.title }}" href="{{ toc_item.url }}">
-                  {{ toc_item.title }}
-                </a>
-              </li>
-            {% endfor %}
-          {% else %}
-          <li class="anchor">
-            <a title="{{ toc_item.title }}" href="{{ toc_item.url }}">
-              {{ toc_item.title }}
-            </a>
-          </li>
-          {% endif %}
-        {% endfor %}
-      </ul>
+      {% if h1 %}
+        {% set toc_item = toc | first %}
+        {% set toc = toc_item.children %}
+      {% endif %}
+      {% if toc %}
+        <ul>
+          {% for toc_item in toc %}
+            <li class="anchor">
+              <a title="{{ toc_item.title }}" href="{{ toc_item.url }}">
+                {{ toc_item.title }}
+              </a>
+            </li>
+          {% endfor %}
+        </ul>
+      {% endif %}
     {% endif %}
   </li>
 {% endif %}

mkdocs.yml

@@ -36,7 +36,7 @@ theme_dir: material
 
 # Options
 extra:
-  version: 0.1.2
+  version: 0.1.3
   logo: images/logo.png
   font:
     text: Ubuntu

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mkdocs-material",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A material design theme for MkDocs",
   "homepage": "http://squidfunk.github.io/mkdocs-material/",
   "authors": [

setup.py

@@ -23,7 +23,7 @@ from setuptools import setup, find_packages
 # Package description
 setup(
     name = 'mkdocs-material',
-    version = '0.1.2',
+    version = '0.1.3',
     url = 'http://squidfunk.github.io/mkdocs-material/',
     license = 'MIT',
     description = 'A material design theme for MkDocs',

src/assets/javascripts/application.js

@@ -502,24 +502,26 @@ document.addEventListener('DOMContentLoaded', function() {
  * ------------------------------------------------------------------------- */
 
   /* Get Stars for current repository */
-  pegasus('https://api.github.com/repos/' + repo_id).then(
+  if (repo_id) {
+    pegasus('https://api.github.com/repos/' + repo_id).then(
 
-    /* Request successful, we got the stars */
-    function(data, xhr) {
-      var count = data.stargazers_count;
-      if (count > 10000)
-        count = (count / 1000).toFixed(0) + 'k';
-      else if (count > 1000)
-        count = (count / 1000).toFixed(1) + 'k';
+      /* Request successful, we got the stars */
+      function(data, xhr) {
+        var count = data.stargazers_count;
+        if (count > 10000)
+          count = (count / 1000).toFixed(0) + 'k';
+        else if (count > 1000)
+          count = (count / 1000).toFixed(1) + 'k';
 
-      /* Set number of stars */
-      var stars = document.querySelector('.repo-stars .count');
-      stars.innerHTML = count;
-    },
+        /* Set number of stars */
+        var stars = document.querySelector('.repo-stars .count');
+        stars.innerHTML = count;
+      },
 
-    /* Handle error */
-    function(data, xhr) {
-      console.error(data, xhr.status);
-    }
-  );
+      /* Handle error */
+      function(data, xhr) {
+        console.error(data, xhr.status);
+      }
+    );
+  }
 });

src/assets/stylesheets/modules/article/_layout.scss

@@ -149,6 +149,13 @@
     margin-top: 1.5em;
   }
 
+  /*
+   * Smaler top spacing for nested lists
+   */
+  li ul, li ol {
+    margin-top: 0.75em;
+  }
+
   /*
    * List elements
    */
@@ -167,7 +174,7 @@
   /*
    * Add icon for elements of an unordered list
    */
-  ul li:before {
+  ul > li:before {
     content: "\e602";
     display: block;
     float: left;

src/base.html

@@ -96,7 +96,7 @@
       {% if config.extra.font and config.extra.font.code %}
         {% set code = config.extra.font.code %}
       {% endif %}
-      {% set font = text + ':400,700|' + code | replace('+', ' ') %}
+      {% set font = text + ':400,700|' + code | replace(' ', '+') %}
       <link rel="stylesheet" type="text/css"
         href="//fonts.googleapis.com/css?family={{ font }}" />
       <style>
@@ -114,6 +114,9 @@
       <link rel="stylesheet" type="text/css" href="{{ path }}" />
     {% endfor %}
 
+    <!-- Modernizr -->
+    <script src="{{ base_url }}/assets/javascripts/modernizr.js"></script>
+
     <!-- Custom header -->
     {% block extrahead %}{% endblock %}
   </head>
@@ -124,7 +127,7 @@
       regular expressions out-of-the-box. Since there might be a slash at the
       end of the repository name, we just do a string comparison and kill it.
     -->
-    {% if repo_name == 'GitHub' %}
+    {% if repo_name == 'GitHub' and repo_url %}
       {% set repo_id = repo_url | replace('https://github.com/', '') %}
       {% if repo_id[-1:] == '/' %}
         {% set repo_id = repo_id[:-1] %}
@@ -215,9 +218,6 @@
       </div>
     </main>
 
-    <!-- Modernizr -->
-    <script src="{{ base_url }}/assets/javascripts/modernizr.js"></script>
-
     <!-- Theme-related and custom javascripts -->
     <script>
       var base_url = '{{ base_url }}';

src/drawer.html

@@ -1,8 +1,9 @@
 <!-- Navigation -->
 <nav aria-label="Navigation">
+  {% set home = repo_url | default('/', true) %}
 
   <!-- Project information -->
-  <a href="{{ repo_url }}" class="project">
+  <a href="{{ home }}" class="project">
 
     <!-- Name and logo -->
     <div class="banner">
@@ -32,7 +33,7 @@
     <div class="wrapper">
 
       <!-- Repository -->
-      {% if repo_name == 'GitHub' %}
+      {% if repo_name == 'GitHub' and repo_url %}
         <ul class="repo">
           <li class="repo-download">
             {% set version = config.extra.version | default('master') %}

src/nav.html

@@ -21,38 +21,32 @@
 
     <!-- Expand active pages -->
     {% if nav_item == current_page %}
-      <ul>
 
-        <!-- Render anchors of active page -->
-        {% for toc_item in toc %}
+      <!--
+        The top-level anchor must be skipped if the article contains a h1
+        headline, since it would be redundant to the link to the current page
+        that is located just above the anchor. Therefore we directly continue
+        with the children of the anchor.
+      -->
+      {% if h1 %}
+        {% set toc_item = toc | first %}
+        {% set toc = toc_item.children %}
+      {% endif %}
 
-          <!--
-            The top-level anchor must be skipped if the article contains a h1
-            headline, since it would be redundant to the link to the current
-            page that is located just above the anchor. Therefore we directly
-            continue with the children of the anchor.
-          -->
-          {% if h1 %}
-            {% for toc_item in toc_item.children %}
+      <!-- Render anchors of active page -->
+      {% if toc %}
+        <ul>
+          {% for toc_item in toc %}
 
-              <!-- Render anchor -->
-              <li class="anchor">
-                <a title="{{ toc_item.title }}" href="{{ toc_item.url }}">
-                  {{ toc_item.title }}
-                </a>
-              </li>
-            {% endfor %}
-          {% else %}
-
-          <!-- Render anchor -->
-          <li class="anchor">
-            <a title="{{ toc_item.title }}" href="{{ toc_item.url }}">
-              {{ toc_item.title }}
-            </a>
-          </li>
-          {% endif %}
-        {% endfor %}
-      </ul>
+            <!-- Render anchor -->
+            <li class="anchor">
+              <a title="{{ toc_item.title }}" href="{{ toc_item.url }}">
+                {{ toc_item.title }}
+              </a>
+            </li>
+          {% endfor %}
+        </ul>
+      {% endif %}
     {% endif %}
   </li>
 {% endif %}