Added syntax highlighting with highlight.js Closes #31 + Added a new chapter to the docs #30.

This commit is contained in:
Mathieu David 2015-08-05 18:28:59 +02:00
parent 191f594e78
commit 90719f721b
25 changed files with 1005 additions and 36 deletions

View File

@ -10,11 +10,12 @@
<link rel="stylesheet" href="book.css" media="screen" title="no title" charset="utf-8">
<link href='http://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link rel="stylesheet" href="highlight.css" media="screen" title="no title" charset="utf-8">
</head>
<body>
<div id="sidebar" class="sidebar">
<ul class="chapter"><li><a href="README.html"class="active"><strong>1.</strong> mdBook</a></li><li><a href="cli/cli-tool.html"><strong>2.</strong> Command Line Tool</a></li><li><ul class="section"><li><a href="cli/init.html"><strong>2.1.</strong> init</a></li><li><a href="cli/build.html"><strong>2.2.</strong> build</a></li></ul><li><strong>3.</strong> Format</li><li><ul class="section"><li><strong>3.1.</strong> SUMMARY.md</li><li><a href="format/config.html"><strong>3.2.</strong> Configuration</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
<ul class="chapter"><li><a href="README.html"class="active"><strong>1.</strong> mdBook</a></li><li><a href="cli/cli-tool.html"><strong>2.</strong> Command Line Tool</a></li><li><ul class="section"><li><a href="cli/init.html"><strong>2.1.</strong> init</a></li><li><a href="cli/build.html"><strong>2.2.</strong> build</a></li></ul><li><strong>3.</strong> Format</li><li><ul class="section"><li><strong>3.1.</strong> SUMMARY.md</li><li><a href="format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="format/theme.html"><strong>3.3.</strong> Theme</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div>
<div id="page-wrapper" class="page-wrapper">
@ -56,6 +57,7 @@ Issues and feature requests can be posted on the <a href="https://github.com/aze
</div>
<script src="http://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="highlight.js"></script>
<script src="book.js"></script>
</body>
</html>

View File

@ -155,16 +155,6 @@ html, body {
opacity: 1;
}
pre {
padding: 16px;
overflow: auto;
font-size: 85%;
line-height: 1.45;
background-color: #f7f7f7;
border: 0;
border-radius: 3px;
}
.left {
float: left;
}

View File

@ -1,5 +1,16 @@
$( document ).ready(function() {
// Syntax highlighting Configuration
hljs.configure({
tabReplace: ' ', // 4 spaces
languages: [], // Languages used for auto-detection
});
$('code').each(function(i, block) {
hljs.highlightBlock(block);
});
// Interesting DOM Elements
var sidebar = $("#sidebar");
var page_wrapper = $("#page-wrapper");

View File

@ -10,11 +10,12 @@
<link rel="stylesheet" href="../book.css" media="screen" title="no title" charset="utf-8">
<link href='http://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link rel="stylesheet" href="../highlight.css" media="screen" title="no title" charset="utf-8">
</head>
<body>
<div id="sidebar" class="sidebar">
<ul class="chapter"><li><a href="../README.html"><strong>1.</strong> mdBook</a></li><li><a href="../cli/cli-tool.html"><strong>2.</strong> Command Line Tool</a></li><li><ul class="section"><li><a href="../cli/init.html"><strong>2.1.</strong> init</a></li><li><a href="../cli/build.html"class="active"><strong>2.2.</strong> build</a></li></ul><li><strong>3.</strong> Format</li><li><ul class="section"><li><strong>3.1.</strong> SUMMARY.md</li><li><a href="../format/config.html"><strong>3.2.</strong> Configuration</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
<ul class="chapter"><li><a href="../README.html"><strong>1.</strong> mdBook</a></li><li><a href="../cli/cli-tool.html"><strong>2.</strong> Command Line Tool</a></li><li><ul class="section"><li><a href="../cli/init.html"><strong>2.1.</strong> init</a></li><li><a href="../cli/build.html"class="active"><strong>2.2.</strong> build</a></li></ul><li><strong>3.</strong> Format</li><li><ul class="section"><li><strong>3.1.</strong> SUMMARY.md</li><li><a href="../format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="../format/theme.html"><strong>3.3.</strong> Theme</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div>
<div id="page-wrapper" class="page-wrapper">
@ -40,7 +41,7 @@ current working directory.</p>
<pre><code>mdbook build path/to/book
</code></pre>
<hr />
<p><strong>note:</strong> make sure to run the build command in the root directory and not in the <code>src</code> directory</p>
<p><strong>note:</strong> make sure to run the build command in the root directory and not in the source directory</p>
</div>
</div>
@ -67,6 +68,7 @@ current working directory.</p>
</div>
<script src="http://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
</body>
</html>

View File

@ -10,11 +10,12 @@
<link rel="stylesheet" href="../book.css" media="screen" title="no title" charset="utf-8">
<link href='http://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link rel="stylesheet" href="../highlight.css" media="screen" title="no title" charset="utf-8">
</head>
<body>
<div id="sidebar" class="sidebar">
<ul class="chapter"><li><a href="../README.html"><strong>1.</strong> mdBook</a></li><li><a href="../cli/cli-tool.html"class="active"><strong>2.</strong> Command Line Tool</a></li><li><ul class="section"><li><a href="../cli/init.html"><strong>2.1.</strong> init</a></li><li><a href="../cli/build.html"><strong>2.2.</strong> build</a></li></ul><li><strong>3.</strong> Format</li><li><ul class="section"><li><strong>3.1.</strong> SUMMARY.md</li><li><a href="../format/config.html"><strong>3.2.</strong> Configuration</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
<ul class="chapter"><li><a href="../README.html"><strong>1.</strong> mdBook</a></li><li><a href="../cli/cli-tool.html"class="active"><strong>2.</strong> Command Line Tool</a></li><li><ul class="section"><li><a href="../cli/init.html"><strong>2.1.</strong> init</a></li><li><a href="../cli/build.html"><strong>2.2.</strong> build</a></li></ul><li><strong>3.</strong> Format</li><li><ul class="section"><li><strong>3.1.</strong> SUMMARY.md</li><li><a href="../format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="../format/theme.html"><strong>3.3.</strong> Theme</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div>
<div id="page-wrapper" class="page-wrapper">
@ -55,6 +56,7 @@ Let's focus on the command line tool capabilities first.</p>
</div>
<script src="http://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
</body>
</html>

View File

@ -10,11 +10,12 @@
<link rel="stylesheet" href="../book.css" media="screen" title="no title" charset="utf-8">
<link href='http://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link rel="stylesheet" href="../highlight.css" media="screen" title="no title" charset="utf-8">
</head>
<body>
<div id="sidebar" class="sidebar">
<ul class="chapter"><li><a href="../README.html"><strong>1.</strong> mdBook</a></li><li><a href="../cli/cli-tool.html"><strong>2.</strong> Command Line Tool</a></li><li><ul class="section"><li><a href="../cli/init.html"class="active"><strong>2.1.</strong> init</a></li><li><a href="../cli/build.html"><strong>2.2.</strong> build</a></li></ul><li><strong>3.</strong> Format</li><li><ul class="section"><li><strong>3.1.</strong> SUMMARY.md</li><li><a href="../format/config.html"><strong>3.2.</strong> Configuration</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
<ul class="chapter"><li><a href="../README.html"><strong>1.</strong> mdBook</a></li><li><a href="../cli/cli-tool.html"><strong>2.</strong> Command Line Tool</a></li><li><ul class="section"><li><a href="../cli/init.html"class="active"><strong>2.1.</strong> init</a></li><li><a href="../cli/build.html"><strong>2.2.</strong> build</a></li></ul><li><strong>3.</strong> Format</li><li><ul class="section"><li><strong>3.1.</strong> SUMMARY.md</li><li><a href="../format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="../format/theme.html"><strong>3.3.</strong> Theme</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div>
<div id="page-wrapper" class="page-wrapper">
@ -84,6 +85,7 @@ not create the corresponding files, init command should create the files for him
</div>
<script src="http://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
</body>
</html>

View File

@ -10,11 +10,12 @@
<link rel="stylesheet" href="../book.css" media="screen" title="no title" charset="utf-8">
<link href='http://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link rel="stylesheet" href="../highlight.css" media="screen" title="no title" charset="utf-8">
</head>
<body>
<div id="sidebar" class="sidebar">
<ul class="chapter"><li><a href="../README.html"><strong>1.</strong> mdBook</a></li><li><a href="../cli/cli-tool.html"><strong>2.</strong> Command Line Tool</a></li><li><ul class="section"><li><a href="../cli/init.html"><strong>2.1.</strong> init</a></li><li><a href="../cli/build.html"><strong>2.2.</strong> build</a></li></ul><li><strong>3.</strong> Format</li><li><ul class="section"><li><strong>3.1.</strong> SUMMARY.md</li><li><a href="../format/config.html"class="active"><strong>3.2.</strong> Configuration</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
<ul class="chapter"><li><a href="../README.html"><strong>1.</strong> mdBook</a></li><li><a href="../cli/cli-tool.html"><strong>2.</strong> Command Line Tool</a></li><li><ul class="section"><li><a href="../cli/init.html"><strong>2.1.</strong> init</a></li><li><a href="../cli/build.html"><strong>2.2.</strong> build</a></li></ul><li><strong>3.</strong> Format</li><li><ul class="section"><li><strong>3.1.</strong> SUMMARY.md</li><li><a href="../format/config.html"class="active"><strong>3.2.</strong> Configuration</a></li><li><a href="../format/theme.html"><strong>3.3.</strong> Theme</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div>
<div id="page-wrapper" class="page-wrapper">
@ -27,9 +28,9 @@
<div id="content" class="content">
<h1>Configuration</h1>
<p>You can configure the parameters for your book in the <code>book.json</code> file.</p>
<p>Here is an example of what a <code>book.json</code> file might look like:</p>
<pre><code>{
<p>You can configure the parameters for your book in the <em>book.json</em> file.</p>
<p>Here is an example of what a <em>book.json</em> file might look like:</p>
<pre><code class="language-json">{
&quot;title&quot;: &quot;Example book&quot;,
&quot;author&quot;: &quot;Name&quot;,
}
@ -38,7 +39,7 @@
<ul>
<li><strong>title:</strong> title of the book</li>
<li><strong>author:</strong> author of the book</li>
<li><strong>dest:</strong> path to the directory where you want your book to be rendered. If a relative path is given it will be relative to the parent directory of <code>src</code></li>
<li><strong>dest:</strong> path to the directory where you want your book to be rendered. If a relative path is given it will be relative to the parent directory of the source directory</li>
</ul>
</div>
@ -57,11 +58,16 @@
<!-- -->
<a href="../format/theme.html" class="nav-chapters next">
<i class="fa fa-angle-right"></i>
</a>
<!-- -->
</div>
<script src="http://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
</body>
</html>

View File

@ -0,0 +1,154 @@
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>mdBook Documentation</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="{% block description %}{% endblock %}">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="../book.css" media="screen" title="no title" charset="utf-8">
<link href='http://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link rel="stylesheet" href="../highlight.css" media="screen" title="no title" charset="utf-8">
</head>
<body>
<div id="sidebar" class="sidebar">
<ul class="chapter"><li><a href="../README.html"><strong>1.</strong> mdBook</a></li><li><a href="../cli/cli-tool.html"><strong>2.</strong> Command Line Tool</a></li><li><ul class="section"><li><a href="../cli/init.html"><strong>2.1.</strong> init</a></li><li><a href="../cli/build.html"><strong>2.2.</strong> build</a></li></ul><li><strong>3.</strong> Format</li><li><ul class="section"><li><strong>3.1.</strong> SUMMARY.md</li><li><a href="../format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="../format/theme.html"class="active"><strong>3.3.</strong> Theme</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar" class="menu-bar">
<i id="sidebar-toggle" class="fa fa-bars left"></i>
<h1 class="menu-title">mdBook Documentation</h1>
</div>
<div id="content" class="content">
<h1>Theme</h1>
<p>The default renderer uses a <a href="http://handlebarsjs.com/">handlebars</a> template to render your markdown files in and comes with a default theme
included in the mdBook binary.</p>
<p>But the theme is totally customizable, you can replace every file from the theme by your own by adding a
<code>theme</code> directory in your source folder. Create a new file with the name of the file you want to overwrite
and now that file will be used instead of the default file.</p>
<p>Here are the files you can overwrite:</p>
<ul>
<li><strong><em>index.hbs</em></strong> is the handlebars template.</li>
<li><strong><em>book.css</em></strong> is the style used in the output. If you want to change the design of your book, this is probably the file you want to modify. Sometimes in conjunction with <code>index.hbs</code> when you want to radically change the layout.</li>
<li><strong><em>book.js</em></strong> is mostly used to add client side functionality.</li>
</ul>
<p><strong>Note:</strong></p>
<p>When you overwrite a file, it is possible that you break some functionality. Therefore I recommend to use the file from the default theme as template and only add / modify what you need. In the future you will be able to copy the default theme into your source directory automatically by using <code>mdbook init --theme</code>.</p>
<h3>Syntax Highlighting</h3>
<p>For syntax highlighting I use <a href="https://highlightjs.org">Highlight.js</a> with the <strong>Monokai Sublime</strong> theme as default.
But if you want a different theme, just put a <code>highlight.css</code> file in your theme folder and your theme will be used.</p>
<ul>
<li><strong><em>highlight.js</em></strong> normally you shouldn't have to overwrite this file. But if you need to, you can.</li>
<li><strong><em>highlight.css</em></strong> theme used by highlight.js for syntax highlighting.</li>
</ul>
<p>When write code blocks in your markdown you will probably want to specify the language you use</p>
<pre><code class="language-markdown">```rust
</code></pre>
<h2>Handlebars</h2>
<h3>Data</h3>
<p>A lot of data is exposed to the handlebars template with the &quot;context&quot;.
In the handlebars template you can access this information by using</p>
<pre><code class="language-handlebars">{{name_of_property}}
</code></pre>
<p>Here is a list of the properties that are exposed:</p>
<ul>
<li>
<p><strong><em>language</em></strong> Language of the book in the form <code>en</code>. To use in <code class="language-html">&lt;html lang=&quot;{{ language }}&quot;&gt;</code> for example.
At the moment it is hardcoded.</p>
</li>
<li>
<p><strong><em>title</em></strong> Title of the book, as specified in <code>book.json</code></p>
</li>
<li>
<p><strong><em>path</em></strong> Relative path to the original markdown file from the source directory</p>
</li>
<li>
<p><strong><em>content</em></strong> This is the rendered markdown.</p>
</li>
<li>
<p><strong><em>path_to_root</em></strong> This is a path containing exclusively <code>../</code>'s that points to the root of the book from the current file.
Since the original directory structure is maintained, it is useful to prepend relative links with this <code>path_to_root</code>.</p>
</li>
<li>
<p><strong><em>chapters</em></strong> Is an array of dictionaries of the form</p>
<pre><code class="language-json">{&quot;section&quot;: &quot;1.2.1&quot;, &quot;name&quot;: &quot;name of this chapter&quot;, &quot;path&quot;: &quot;dir/markdown.md&quot;}
</code></pre>
<p>containing all the chapters of the book. It is used for example to construct the table of contents (sidebar).</p>
</li>
</ul>
<h3>Helpers</h3>
<p>In addition to the properties you can access, there are some handlebars helpers at your disposal.</p>
<ol>
<li>
<h3>toc</h3>
<p>The toc helper is used like this</p>
<pre><code class="language-handlebars">{{#toc}}{{/toc}}
</code></pre>
<p>and outputs something that looks like this, depending on the structure of your book</p>
<pre><code class="language-html">&lt;ul class=&quot;chapter&quot;&gt;
&lt;li&gt;&lt;a href=&quot;link/to/file.html&quot;&gt;Some chapter&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;
&lt;ul class=&quot;section&quot;&gt;
&lt;li&gt;&lt;a href=&quot;link/to/other_file.html&quot;&gt;Some other Chapter&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;
</code></pre>
<p>If you would like to make a toc with another structure, you have access to the chapters property containing all the data.
The only limitation at the moment is that you would have to do it with JavaScript instead of with a handlebars helper.</p>
<pre><code class="language-html">&lt;script&gt;
var chapters = {{chapters}};
// Processing here
&lt;/script&gt;
</code></pre>
</li>
<li>
<h3>previous / next</h3>
<p>The previous and next helpers expose a <code>link</code> and <code>name</code> property to the previous and next chapters.</p>
<p>They are used like this</p>
<pre><code class="language-handlebars">{{#previous}}
&lt;a href=&quot;{{link}}&quot; class=&quot;nav-chapters previous&quot;&gt;
&lt;i class=&quot;fa fa-angle-left&quot;&gt;&lt;/i&gt;
&lt;/a&gt;
{{/previous}}
</code></pre>
<p>The inner html will only be rendered if the previous / next chapter exists.
Of course the inner html can be changed to your liking.</p>
</li>
</ol>
<hr />
<p>If you would like me to expose other properties or helpers, please <a href="https://github.com/azerupi/mdBook/issues">create a new issue</a>
and I will consider it.</p>
</div>
</div>
<!--
Doesn't seem to work: using JavaScript
alternative until I find a way to do it in the template
-->
<a href="../format/config.html" class="nav-chapters previous">
<i class="fa fa-angle-left"></i>
</a>
<!-- -->
<!-- -->
<!-- -->
</div>
<script src="http://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="../highlight.js"></script>
<script src="../book.js"></script>
</body>
</html>

View File

@ -0,0 +1,162 @@
/*
Monokai Sublime style. Derived from Monokai by noformnocontent http://nn.mit-license.org/
*/
.hljs {
display: block;
overflow-x: auto;
padding: 0.5em;
background: #23241f;
border-radius: 4px;
-webkit-text-size-adjust: none;
}
/* Inline code */
:not(pre) > .hljs {
display: inline-block;
padding: 0.1em 0.3em;
border-radius: 3px;
}
.hljs,
.hljs-tag,
.css .hljs-rule,
.css .hljs-value,
.aspectj .hljs-function,
.css .hljs-function
.hljs-preprocessor,
.hljs-pragma {
color: #f8f8f2;
}
.hljs-strongemphasis,
.hljs-strong,
.hljs-emphasis {
color: #a8a8a2;
}
.hljs-bullet,
.hljs-blockquote,
.hljs-horizontal_rule,
.hljs-number,
.hljs-regexp,
.alias .hljs-keyword,
.hljs-literal,
.hljs-hexcolor {
color: #ae81ff;
}
.hljs-tag .hljs-value,
.hljs-code,
.hljs-title,
.css .hljs-class,
.hljs-class .hljs-title:last-child {
color: #a6e22e;
}
.hljs-link_url {
font-size: 80%;
}
.hljs-strong,
.hljs-strongemphasis {
font-weight: bold;
}
.hljs-emphasis,
.hljs-strongemphasis,
.hljs-class .hljs-title:last-child,
.hljs-typename {
font-style: italic;
}
.hljs-keyword,
.ruby .hljs-class .hljs-keyword:first-child,
.ruby .hljs-function .hljs-keyword,
.hljs-function,
.hljs-change,
.hljs-winutils,
.hljs-flow,
.nginx .hljs-title,
.tex .hljs-special,
.hljs-header,
.hljs-attribute,
.hljs-symbol,
.hljs-symbol .hljs-string,
.hljs-tag .hljs-title,
.hljs-value,
.alias .hljs-keyword:first-child,
.css .hljs-tag,
.css .unit,
.css .hljs-important {
color: #f92672;
}
.hljs-function .hljs-keyword,
.hljs-class .hljs-keyword:first-child,
.hljs-aspect .hljs-keyword:first-child,
.hljs-constant,
.hljs-typename,
.hljs-name,
.css .hljs-attribute {
color: #66d9ef;
}
.hljs-variable,
.hljs-params,
.hljs-class .hljs-title,
.hljs-aspect .hljs-title {
color: #f8f8f2;
}
.hljs-string,
.css .hljs-id,
.hljs-subst,
.hljs-type,
.ruby .hljs-class .hljs-parent,
.hljs-built_in,
.django .hljs-template_tag,
.django .hljs-variable,
.smalltalk .hljs-class,
.django .hljs-filter .hljs-argument,
.smalltalk .hljs-localvars,
.smalltalk .hljs-array,
.hljs-attr_selector,
.hljs-pseudo,
.hljs-addition,
.hljs-stream,
.hljs-envvar,
.apache .hljs-tag,
.apache .hljs-cbracket,
.tex .hljs-command,
.hljs-prompt,
.hljs-link_label,
.hljs-link_url {
color: #e6db74;
}
.hljs-comment,
.hljs-annotation,
.hljs-decorator,
.hljs-pi,
.hljs-doctype,
.hljs-deletion,
.hljs-shebang,
.apache .hljs-sqbracket,
.tex .hljs-formula {
color: #75715e;
}
.coffeescript .javascript,
.javascript .xml,
.tex .hljs-formula,
.xml .javascript,
.xml .vbscript,
.xml .css,
.xml .hljs-cdata,
.xml .php,
.php .xml {
opacity: 0.5;
}

File diff suppressed because one or more lines are too long

View File

@ -10,11 +10,12 @@
<link rel="stylesheet" href="book.css" media="screen" title="no title" charset="utf-8">
<link href='http://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link rel="stylesheet" href="highlight.css" media="screen" title="no title" charset="utf-8">
</head>
<body>
<div id="sidebar" class="sidebar">
<ul class="chapter"><li><a href="README.html"class="active"><strong>1.</strong> mdBook</a></li><li><a href="cli/cli-tool.html"><strong>2.</strong> Command Line Tool</a></li><li><ul class="section"><li><a href="cli/init.html"><strong>2.1.</strong> init</a></li><li><a href="cli/build.html"><strong>2.2.</strong> build</a></li></ul><li><strong>3.</strong> Format</li><li><ul class="section"><li><strong>3.1.</strong> SUMMARY.md</li><li><a href="format/config.html"><strong>3.2.</strong> Configuration</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
<ul class="chapter"><li><a href="README.html"class="active"><strong>1.</strong> mdBook</a></li><li><a href="cli/cli-tool.html"><strong>2.</strong> Command Line Tool</a></li><li><ul class="section"><li><a href="cli/init.html"><strong>2.1.</strong> init</a></li><li><a href="cli/build.html"><strong>2.2.</strong> build</a></li></ul><li><strong>3.</strong> Format</li><li><ul class="section"><li><strong>3.1.</strong> SUMMARY.md</li><li><a href="format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="format/theme.html"><strong>3.3.</strong> Theme</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div>
<div id="page-wrapper" class="page-wrapper">
@ -56,6 +57,7 @@ Issues and feature requests can be posted on the <a href="https://github.com/aze
</div>
<script src="http://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="highlight.js"></script>
<script src="book.js"></script>
</body>
</html>

238
book-example/book/prism.css Normal file
View File

@ -0,0 +1,238 @@
/* http://prismjs.com/download.html?themes=prism-okaidia&languages=markup+css+clike+javascript */
/**
* okaidia theme for JavaScript, CSS and HTML
* Loosely based on Monokai textmate theme by http://www.monokai.nl/
* @author ocodia
*/
code,
pre {
color: #333;
font-family: Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace;
direction: ltr;
text-align: left;
white-space: pre;
word-spacing: normal;
word-break: normal;
line-height: 1.5;
-moz-tab-size: 4;
-o-tab-size: 4;
tab-size: 4;
-webkit-hyphens: none;
-moz-hyphens: none;
-ms-hyphens: none;
hyphens: none;
}
/* Code blocks */
pre {
padding: 1em;
margin: .5em 0;
overflow: auto;
border-radius: 0.3em;
}
:not(pre) > code,
pre {
background: #f7f7f7;
}
/* Inline code */
:not(pre) > code {
padding: .2em;
border-radius: .2em;
}
.token.comment,
.token.prolog,
.token.doctype,
.token.cdata {
color: slategray;
}
.token.punctuation {
color: #333;
}
.namespace {
opacity: .7;
}
.token.property,
.token.tag,
.token.constant,
.token.symbol,
.token.deleted {
color: #f92672;
}
.token.boolean,
.token.number {
color: #ae81ff;
}
.token.selector,
.token.attr-name,
.token.string,
.token.char,
.token.builtin,
.token.inserted {
color: #a6e22e;
}
.token.operator,
.token.entity,
.token.url,
.language-css .token.string,
.style .token.string,
.token.variable {
color: #CCC;
}
.token.atrule,
.token.attr-value,
.token.function {
color: #e6db74;
}
.token.keyword {
color: #66d9ef;
}
.token.regex,
.token.important {
color: #fd971f;
}
.token.important,
.token.bold {
font-weight: bold;
}
.token.italic {
font-style: italic;
}
.token.entity {
cursor: help;
}
/* http://prismjs.com/download.html?themes=prism-okaidia&languages=markup+css+clike+javascript */
/**
* okaidia theme for JavaScript, CSS and HTML
* Loosely based on Monokai textmate theme by http://www.monokai.nl/
* @author ocodia
*/
code,
pre {
color: #333;
font-family: Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace;
direction: ltr;
text-align: left;
white-space: pre;
word-spacing: normal;
word-break: normal;
line-height: 1.5;
-moz-tab-size: 4;
-o-tab-size: 4;
tab-size: 4;
-webkit-hyphens: none;
-moz-hyphens: none;
-ms-hyphens: none;
hyphens: none;
}
/* Code blocks */
pre {
padding: 1em;
margin: .5em 0;
overflow: auto;
border-radius: 0.3em;
}
:not(pre) > code,
pre {
background: #f7f7f7;
}
/* Inline code */
:not(pre) > code {
padding: .2em;
border-radius: .2em;
}
.token.comment,
.token.prolog,
.token.doctype,
.token.cdata {
color: slategray;
}
.token.punctuation {
color: #333;
}
.namespace {
opacity: .7;
}
.token.property,
.token.tag,
.token.constant,
.token.symbol,
.token.deleted {
color: #f92672;
}
.token.boolean,
.token.number {
color: #ae81ff;
}
.token.selector,
.token.attr-name,
.token.string,
.token.char,
.token.builtin,
.token.inserted {
color: #a6e22e;
}
.token.operator,
.token.entity,
.token.url,
.language-css .token.string,
.style .token.string,
.token.variable {
color: #555;
}
.token.atrule,
.token.attr-value,
.token.function {
color: #e6db74;
}
.token.keyword {
color: #66d9ef;
}
.token.regex,
.token.important {
color: #fd971f;
}
.token.important,
.token.bold {
font-weight: bold;
}
.token.italic {
font-style: italic;
}
.token.entity {
cursor: help;
}

File diff suppressed because one or more lines are too long

View File

@ -7,4 +7,5 @@
- [Format]()
- [SUMMARY.md]()
- [Configuration](format/config.md)
- [Theme](format/theme.md)
- [Rust Library]()

View File

@ -23,4 +23,4 @@ mdbook build path/to/book
-------------------
**note:** make sure to run the build command in the root directory and not in the `src` directory
**note:** make sure to run the build command in the root directory and not in the source directory

View File

@ -1,10 +1,10 @@
# Configuration
You can configure the parameters for your book in the `book.json` file.
You can configure the parameters for your book in the *book.json* file.
Here is an example of what a `book.json` file might look like:
Here is an example of what a *book.json* file might look like:
```
```json
{
"title": "Example book",
"author": "Name",
@ -15,4 +15,4 @@ Here is an example of what a `book.json` file might look like:
- **title:** title of the book
- **author:** author of the book
- **dest:** path to the directory where you want your book to be rendered. If a relative path is given it will be relative to the parent directory of `src`
- **dest:** path to the directory where you want your book to be rendered. If a relative path is given it will be relative to the parent directory of the source directory

View File

@ -0,0 +1,118 @@
# Theme
The default renderer uses a [handlebars](http://handlebarsjs.com/) template to render your markdown files in and comes with a default theme
included in the mdBook binary.
But the theme is totally customizable, you can replace every file from the theme by your own by adding a
`theme` directory in your source folder. Create a new file with the name of the file you want to overwrite
and now that file will be used instead of the default file.
Here are the files you can overwrite:
- ***index.hbs*** is the handlebars template.
- ***book.css*** is the style used in the output. If you want to change the design of your book, this is probably the file you want to modify. Sometimes in conjunction with `index.hbs` when you want to radically change the layout.
- ***book.js*** is mostly used to add client side functionality.
**Note:**
When you overwrite a file, it is possible that you break some functionality. Therefore I recommend to use the file from the default theme as template and only add / modify what you need. In the future you will be able to copy the default theme into your source directory automatically by using `mdbook init --theme`.
### Syntax Highlighting
For syntax highlighting I use [Highlight.js](https://highlightjs.org) with the **Monokai Sublime** theme as default.
But if you want a different theme, just put a `highlight.css` file in your theme folder and your theme will be used.
- ***highlight.js*** normally you shouldn't have to overwrite this file. But if you need to, you can.
- ***highlight.css*** theme used by highlight.js for syntax highlighting.
When write code blocks in your markdown you will probably want to specify the language you use
```markdown
```rust
```
## Handlebars
### Data
A lot of data is exposed to the handlebars template with the "context".
In the handlebars template you can access this information by using
```handlebars
{{name_of_property}}
```
Here is a list of the properties that are exposed:
- ***language*** Language of the book in the form `en`. To use in <code class="language-html">\<html lang="{{ language }}"></code> for example.
At the moment it is hardcoded.
- ***title*** Title of the book, as specified in `book.json`
- ***path*** Relative path to the original markdown file from the source directory
- ***content*** This is the rendered markdown.
- ***path_to_root*** This is a path containing exclusively `../`'s that points to the root of the book from the current file.
Since the original directory structure is maintained, it is useful to prepend relative links with this `path_to_root`.
- ***chapters*** Is an array of dictionaries of the form
```json
{"section": "1.2.1", "name": "name of this chapter", "path": "dir/markdown.md"}
```
containing all the chapters of the book. It is used for example to construct the table of contents (sidebar).
### Helpers
In addition to the properties you can access, there are some handlebars helpers at your disposal.
1. ### toc
The toc helper is used like this
```handlebars
{{#toc}}{{/toc}}
```
and outputs something that looks like this, depending on the structure of your book
```html
<ul class="chapter">
<li><a href="link/to/file.html">Some chapter</a></li>
<li>
<ul class="section">
<li><a href="link/to/other_file.html">Some other Chapter</a></li>
</ul>
</li>
</ul>
```
If you would like to make a toc with another structure, you have access to the chapters property containing all the data.
The only limitation at the moment is that you would have to do it with JavaScript instead of with a handlebars helper.
```html
<script>
var chapters = {{chapters}};
// Processing here
</script>
```
2. ### previous / next
The previous and next helpers expose a `link` and `name` property to the previous and next chapters.
They are used like this
```handlebars
{{#previous}}
<a href="{{link}}" class="nav-chapters previous">
<i class="fa fa-angle-left"></i>
</a>
{{/previous}}
```
The inner html will only be rendered if the previous / next chapter exists.
Of course the inner html can be changed to your liking.
------
If you would like me to expose other properties or helpers, please [create a new issue](https://github.com/azerupi/mdBook/issues)
and I will consider it.

View File

@ -121,6 +121,12 @@ impl Renderer for HtmlHandlebars {
let mut css_file = try!(File::create(config.dest().join("book.css")));
try!(css_file.write_all(&theme.css));
// syntax highlighting
let mut highlight_css = try!(File::create(config.dest().join("highlight.css")));
try!(highlight_css.write_all(&theme.highlight_css));
let mut highlight_js = try!(File::create(config.dest().join("highlight.js")));
try!(highlight_js.write_all(&theme.highlight_js));
Ok(())
}
}

View File

@ -7,6 +7,8 @@ pub struct Theme {
pub index: String,
pub css: Vec<u8>,
pub js: Vec<u8>,
pub highlight_css: Vec<u8>,
pub highlight_js: Vec<u8>,
}
impl Theme {
@ -17,6 +19,8 @@ impl Theme {
index: theme::get_index_hbs().to_owned(),
css: theme::get_css().to_owned(),
js: theme::get_js().to_owned(),
highlight_css: theme::get_highlight_css().to_owned(),
highlight_js: theme::get_highlight_js().to_owned(),
};
// Check if the given path exists
@ -68,6 +72,22 @@ impl Theme {
_ => {},
}
// highlight.js
match File::open(&src.join("highlight.js")) {
Ok(mut f) => {
f.read_to_end(&mut theme.highlight_js).unwrap();
},
_ => {},
}
// highlight.css
match File::open(&src.join("highlight.css")) {
Ok(mut f) => {
f.read_to_end(&mut theme.highlight_css).unwrap();
},
_ => {},
}
theme
}
}

View File

@ -155,16 +155,6 @@ html, body {
opacity: 1;
}
pre {
padding: 16px;
overflow: auto;
font-size: 85%;
line-height: 1.45;
background-color: #f7f7f7;
border: 0;
border-radius: 3px;
}
.left {
float: left;
}

View File

@ -1,5 +1,16 @@
$( document ).ready(function() {
// Syntax highlighting Configuration
hljs.configure({
tabReplace: ' ', // 4 spaces
languages: [], // Languages used for auto-detection
});
$('code').each(function(i, block) {
hljs.highlightBlock(block);
});
// Interesting DOM Elements
var sidebar = $("#sidebar");
var page_wrapper = $("#page-wrapper");

162
src/theme/highlight.css Normal file
View File

@ -0,0 +1,162 @@
/*
Monokai Sublime style. Derived from Monokai by noformnocontent http://nn.mit-license.org/
*/
.hljs {
display: block;
overflow-x: auto;
padding: 0.5em;
background: #23241f;
border-radius: 4px;
-webkit-text-size-adjust: none;
}
/* Inline code */
:not(pre) > .hljs {
display: inline-block;
padding: 0.1em 0.3em;
border-radius: 3px;
}
.hljs,
.hljs-tag,
.css .hljs-rule,
.css .hljs-value,
.aspectj .hljs-function,
.css .hljs-function
.hljs-preprocessor,
.hljs-pragma {
color: #f8f8f2;
}
.hljs-strongemphasis,
.hljs-strong,
.hljs-emphasis {
color: #a8a8a2;
}
.hljs-bullet,
.hljs-blockquote,
.hljs-horizontal_rule,
.hljs-number,
.hljs-regexp,
.alias .hljs-keyword,
.hljs-literal,
.hljs-hexcolor {
color: #ae81ff;
}
.hljs-tag .hljs-value,
.hljs-code,
.hljs-title,
.css .hljs-class,
.hljs-class .hljs-title:last-child {
color: #a6e22e;
}
.hljs-link_url {
font-size: 80%;
}
.hljs-strong,
.hljs-strongemphasis {
font-weight: bold;
}
.hljs-emphasis,
.hljs-strongemphasis,
.hljs-class .hljs-title:last-child,
.hljs-typename {
font-style: italic;
}
.hljs-keyword,
.ruby .hljs-class .hljs-keyword:first-child,
.ruby .hljs-function .hljs-keyword,
.hljs-function,
.hljs-change,
.hljs-winutils,
.hljs-flow,
.nginx .hljs-title,
.tex .hljs-special,
.hljs-header,
.hljs-attribute,
.hljs-symbol,
.hljs-symbol .hljs-string,
.hljs-tag .hljs-title,
.hljs-value,
.alias .hljs-keyword:first-child,
.css .hljs-tag,
.css .unit,
.css .hljs-important {
color: #f92672;
}
.hljs-function .hljs-keyword,
.hljs-class .hljs-keyword:first-child,
.hljs-aspect .hljs-keyword:first-child,
.hljs-constant,
.hljs-typename,
.hljs-name,
.css .hljs-attribute {
color: #66d9ef;
}
.hljs-variable,
.hljs-params,
.hljs-class .hljs-title,
.hljs-aspect .hljs-title {
color: #f8f8f2;
}
.hljs-string,
.css .hljs-id,
.hljs-subst,
.hljs-type,
.ruby .hljs-class .hljs-parent,
.hljs-built_in,
.django .hljs-template_tag,
.django .hljs-variable,
.smalltalk .hljs-class,
.django .hljs-filter .hljs-argument,
.smalltalk .hljs-localvars,
.smalltalk .hljs-array,
.hljs-attr_selector,
.hljs-pseudo,
.hljs-addition,
.hljs-stream,
.hljs-envvar,
.apache .hljs-tag,
.apache .hljs-cbracket,
.tex .hljs-command,
.hljs-prompt,
.hljs-link_label,
.hljs-link_url {
color: #e6db74;
}
.hljs-comment,
.hljs-annotation,
.hljs-decorator,
.hljs-pi,
.hljs-doctype,
.hljs-deletion,
.hljs-shebang,
.apache .hljs-sqbracket,
.tex .hljs-formula {
color: #75715e;
}
.coffeescript .javascript,
.javascript .xml,
.tex .hljs-formula,
.xml .javascript,
.xml .vbscript,
.xml .css,
.xml .hljs-cdata,
.xml .php,
.php .xml {
opacity: 0.5;
}

3
src/theme/highlight.js Normal file

File diff suppressed because one or more lines are too long

View File

@ -10,6 +10,7 @@
<link rel="stylesheet" href="{{ path_to_root }}book.css" media="screen" title="no title" charset="utf-8">
<link href='http://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
<link rel="stylesheet" href="{{ path_to_root }}highlight.css" media="screen" title="no title" charset="utf-8">
</head>
<body>
@ -52,6 +53,7 @@
</div>
<script src="http://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="{{ path_to_root }}highlight.js"></script>
<script src="{{ path_to_root }}book.js"></script>
</body>
</html>

View File

@ -13,3 +13,13 @@ pub fn get_js() -> &'static [u8] {
let js = include_bytes!("book.js");
js
}
pub fn get_highlight_js() -> &'static [u8] {
let highlight_js = include_bytes!("highlight.js");
highlight_js
}
pub fn get_highlight_css() -> &'static [u8] {
let highlight_css = include_bytes!("highlight.css");
highlight_css
}