jekyll-docskimmer-theme
jekyll-docskimmer-theme
jekyll-docskimmer-theme is the official port of docSkimmer theme from MkDocs to Jekyll.
[Demo of Jekyll docSkimmer theme on GitHub Pages]
Features
- accessible;
- responsive;
- valid HTML5 + CSS3;
- no fonts (refer to Customizing Styles section below);
- includes search;
- supports
google_analytics(refer to Configuration section below).
Installation
Add this line to your Jekyll site's Gemfile:
gem "jekyll-docskimmer-theme", :path => 'jekyll-docskimmer-theme'
And then execute:
$ bundle install #(re-)generates Gemfile.lock file
Add this line to your Jekyll site's _config.yml:
theme: jekyll-docskimmer-theme
And then execute:
$ bundle exec jekyll serve #run Jekyll using only gems in Gemfile
(Not on RubyGems yet.)
Usage
Configuration
The following are docSkimmer theme-specific settings in _config.yml:
| Parameter | Format | Description |
|---|---|---|
| author | text example: Your Name |
This name is displayed in 'author' meta tag |
| copyright | text example: Copyright © YYYY Your Name |
Any text here is displayed in the footer wrapped in <p></p> tags |
| google_analytics | tracking ID example: UA-00000000-0 |
(OPTIONAL) Replace numeric placeholders with a Google Analytics property ID to use client-side tracking, or leave blank |
| tagline | text example: Your tagline text |
(OPTIONAL) Displayed in: (1.) 'description' meta tag (after colon) if no 'description' site setting is provided, and/or (2.) as a heading in the main header of the site (note: if no tagline is provided, the site description is displayed as the heading instead) |
The following are theme-specific settings that must be included in the front-matter of each .md file located in the _<your-collection> directory:
| Parameter | Format | Description |
|---|---|---|
| title | text example: Your Page Title |
This text is displayed as the content of the <h1></h1> tag |
| description | text example: A short descriptive paragraph about the page goes here |
This text is displayed as (1.) the 'blurb' for the listing on the homepage/'table of contents' page |
| img | relative URL example: /assets/img/<your-collection-name-without-leading-underscore>/<your-page-name>/<your-image-name>.<image-file-extension> |
(OPTIONAL) May be used to display, for example, a screenshot of the project on its inner details page. MUST follow the naming conventions shown in the example - eg. for an image to be displayed on a project page, first: create a directory in the root of your Jekyll site under /assets/img/ that has the same name as your collection (without the _ in front of it); next: create a sub-directory with the same name as the .md page for the project, and place your image in it. The theme will automatically display the image on the correct page. |
| img_alt | text example: Your image caption text |
(REQUIRED if using 'img') Displayed as alt attribute value if an img is provided |
| docs_url | absolute URL example: https://<path-to-documentation-site>/ |
(OPTIONAL) Links to accompanying documentation site on (1.) the homepage/'table of contents' page blurb, and (2.) on the inner details page for the item |
| repo_url | absolute URL example: https://<path-to-repository>/ |
(OPTIONAL) Links to accompanying repository on (1.) the homepage/'table of contents' page blurb, and (2.) on the inner details page for the item |
| related: - title |
text example: Title of related project |
(OPTIONAL) Appears as link text under 'Related' heading at the bottom of an inner details page for an item |
| related: - description |
text example: Description of related project |
(OPTIONAL) Use for brief description displayed as list item text under 'Related' heading at the bottom of an inner details page for an item |
| related: - url |
relative URL example: /<your-collection-name-without-leading-underscore>/<your-related-page-name>.html |
(REQUIRED if using 'title') Used as href attribute value for link under 'Related' heading at the bottom of an inner details page for an item |
Layouts
Edit the front-matter of the following files to use the layouts indicated (refer to the table below):
| File(s) | Layout |
|---|---|
| index.md 404.html |
default |
| search.md | search (only use for Search Results page) |
(OPTIONAL) all .md files located in the _<your-collection> directory(NOTE: set this in _config.yml not in front-matter) |
page |
Example:
---
layout: default
---
Customizing Styles
Add custom stylesheets to the /assets/css directory in the root of the Jekyll site (not in the theme directory).
Demo
Demo of Jekyll docSkimmer theme on GitHub Pages
Changelog
Note re: version numbers
The features of corresponding version numbers of jekyll-docskimmer-theme and mkdocs-docskimmer are almost identical, with a few exceptions (see notes under 'REMOVED' and 'ADDED' below):
0.1.2 - March 24, 2018. Changed: Position of 'Repo' link on inner pages is now consistent, whether or not an image is included on the page (improved usability).
0.1.1 - December 3, 2017. Initial port of mkdocs-docskimmer (v.0.1.1/latest release) to Jekyll.
REMOVED: Menu panel-related styles and script (not required since collapsable 'On this Page' panel in mkdocs-docskimmer is replaced by the 'table of contents'-style homepage in jekyll-docskimmer-theme); styles related to the second-level top navigation bar.
ADDED: Style customizations required by new jekyll-docskimmer-theme layouts. (These are located in the main theme stylesheet
jekyll-docskimmer-theme.scss.)
License
Copyright (c) 2017 Heini Fagerlund. Licensed under the Simplified BSD License. (See LICENSE.)
This theme includes the following files which are the properties of their respective owners:
- assets/js/analytics.js - Google Analytics
- assets/js/lunr.min.js - Lunr
- assets/js/mustache.min.js - Mustache
- assets/js/require.js - RequireJS
- assets/js/search.js - MkDocs
- assets/js/text.js - RequireJS text