Added some chapters for the documentation #30 + tweaked the syntax highlighting theme

This commit is contained in:
Mathieu David 2015-08-05 20:36:21 +02:00
parent 58d18d467c
commit 991ccb5495
20 changed files with 461 additions and 84 deletions

View File

@ -15,7 +15,7 @@
<body> <body>
<div id="sidebar" class="sidebar"> <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><li><a href="format/theme.html"><strong>3.3.</strong> Theme</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><a href="format/format.html"><strong>3.</strong> Format</a></li><li><ul class="section"><li><a href="format/summary.html"><strong>3.1.</strong> SUMMARY.md</a></li><li><a href="format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="format/theme/theme.html"><strong>3.3.</strong> Theme</a></li><li><ul class="section"><li><a href="format/theme/index-hbs.html"><strong>3.3.1.</strong> index.hbs</a></li><li><a href="format/theme/syntax-highlighting.html"><strong>3.3.2.</strong> Syntax highlighting</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div> </div>
<div id="page-wrapper" class="page-wrapper"> <div id="page-wrapper" class="page-wrapper">

View File

@ -15,7 +15,7 @@
<body> <body>
<div id="sidebar" class="sidebar"> <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><li><a href="../format/theme.html"><strong>3.3.</strong> Theme</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><a href="../format/format.html"><strong>3.</strong> Format</a></li><li><ul class="section"><li><a href="../format/summary.html"><strong>3.1.</strong> SUMMARY.md</a></li><li><a href="../format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="../format/theme/theme.html"><strong>3.3.</strong> Theme</a></li><li><ul class="section"><li><a href="../format/theme/index-hbs.html"><strong>3.3.1.</strong> index.hbs</a></li><li><a href="../format/theme/syntax-highlighting.html"><strong>3.3.2.</strong> Syntax highlighting</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div> </div>
<div id="page-wrapper" class="page-wrapper"> <div id="page-wrapper" class="page-wrapper">
@ -59,7 +59,7 @@ current working directory.</p>
<!-- --> <!-- -->
<a href="../format/config.html" class="nav-chapters next"> <a href="../format/format.html" class="nav-chapters next">
<i class="fa fa-angle-right"></i> <i class="fa fa-angle-right"></i>
</a> </a>

View File

@ -15,7 +15,7 @@
<body> <body>
<div id="sidebar" class="sidebar"> <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><li><a href="../format/theme.html"><strong>3.3.</strong> Theme</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><a href="../format/format.html"><strong>3.</strong> Format</a></li><li><ul class="section"><li><a href="../format/summary.html"><strong>3.1.</strong> SUMMARY.md</a></li><li><a href="../format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="../format/theme/theme.html"><strong>3.3.</strong> Theme</a></li><li><ul class="section"><li><a href="../format/theme/index-hbs.html"><strong>3.3.1.</strong> index.hbs</a></li><li><a href="../format/theme/syntax-highlighting.html"><strong>3.3.2.</strong> Syntax highlighting</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div> </div>
<div id="page-wrapper" class="page-wrapper"> <div id="page-wrapper" class="page-wrapper">

View File

@ -15,7 +15,7 @@
<body> <body>
<div id="sidebar" class="sidebar"> <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><li><a href="../format/theme.html"><strong>3.3.</strong> Theme</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><a href="../format/format.html"><strong>3.</strong> Format</a></li><li><ul class="section"><li><a href="../format/summary.html"><strong>3.1.</strong> SUMMARY.md</a></li><li><a href="../format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="../format/theme/theme.html"><strong>3.3.</strong> Theme</a></li><li><ul class="section"><li><a href="../format/theme/index-hbs.html"><strong>3.3.1.</strong> index.hbs</a></li><li><a href="../format/theme/syntax-highlighting.html"><strong>3.3.2.</strong> Syntax highlighting</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div> </div>
<div id="page-wrapper" class="page-wrapper"> <div id="page-wrapper" class="page-wrapper">
@ -45,7 +45,7 @@ configuration files, etc.</p>
<p>The <code>book</code> directory is where your book is rendered. All the output is ready to be uploaded <p>The <code>book</code> directory is where your book is rendered. All the output is ready to be uploaded
to a serer to be seen by the internet.</p> to a serer to be seen by the internet.</p>
<p>The <code>SUMMARY.md</code> file is the most important file, it's the skeleton of your book. <p>The <code>SUMMARY.md</code> file is the most important file, it's the skeleton of your book.
It's so important that it has it's own <a href="">chapter</a>.</p> It's so important that it has it's own <a href="../format/summary.html">chapter</a>.</p>
<h4>Specify a directory</h4> <h4>Specify a directory</h4>
<p>When using the init command, you can also specify a directory, instead of using the current directory, <p>When using the init command, you can also specify a directory, instead of using the current directory,
by appending a path to the command:</p> by appending a path to the command:</p>

View File

@ -15,7 +15,7 @@
<body> <body>
<div id="sidebar" class="sidebar"> <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><li><a href="../format/theme.html"><strong>3.3.</strong> Theme</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><a href="../format/format.html"><strong>3.</strong> Format</a></li><li><ul class="section"><li><a href="../format/summary.html"><strong>3.1.</strong> SUMMARY.md</a></li><li><a href="../format/config.html"class="active"><strong>3.2.</strong> Configuration</a></li><li><a href="../format/theme/theme.html"><strong>3.3.</strong> Theme</a></li><li><ul class="section"><li><a href="../format/theme/index-hbs.html"><strong>3.3.1.</strong> index.hbs</a></li><li><a href="../format/theme/syntax-highlighting.html"><strong>3.3.2.</strong> Syntax highlighting</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div> </div>
<div id="page-wrapper" class="page-wrapper"> <div id="page-wrapper" class="page-wrapper">
@ -50,7 +50,7 @@
alternative until I find a way to do it in the template alternative until I find a way to do it in the template
--> -->
<a href="../cli/build.html" class="nav-chapters previous"> <a href="../format/summary.html" class="nav-chapters previous">
<i class="fa fa-angle-left"></i> <i class="fa fa-angle-left"></i>
</a> </a>
@ -58,7 +58,7 @@
<!-- --> <!-- -->
<a href="../format/theme.html" class="nav-chapters next"> <a href="../format/theme/theme.html" class="nav-chapters next">
<i class="fa fa-angle-right"></i> <i class="fa fa-angle-right"></i>
</a> </a>

View File

@ -0,0 +1,67 @@
<!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><a href="../format/format.html"class="active"><strong>3.</strong> Format</a></li><li><ul class="section"><li><a href="../format/summary.html"><strong>3.1.</strong> SUMMARY.md</a></li><li><a href="../format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="../format/theme/theme.html"><strong>3.3.</strong> Theme</a></li><li><ul class="section"><li><a href="../format/theme/index-hbs.html"><strong>3.3.1.</strong> index.hbs</a></li><li><a href="../format/theme/syntax-highlighting.html"><strong>3.3.2.</strong> Syntax highlighting</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>Format</h1>
<p>In this section you will learn how to:</p>
<ul>
<li>Structure your book correctly</li>
<li>Format your <code>SUMMARY.md</code> file</li>
<li>Configure your book using <code>book.json</code></li>
<li>Customize your theme</li>
</ul>
</div>
</div>
<!--
Doesn't seem to work: using JavaScript
alternative until I find a way to do it in the template
-->
<a href="../cli/build.html" class="nav-chapters previous">
<i class="fa fa-angle-left"></i>
</a>
<!-- -->
<!-- -->
<a href="../format/summary.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,86 @@
<!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><a href="../format/format.html"><strong>3.</strong> Format</a></li><li><ul class="section"><li><a href="../format/summary.html"class="active"><strong>3.1.</strong> SUMMARY.md</a></li><li><a href="../format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="../format/theme/theme.html"><strong>3.3.</strong> Theme</a></li><li><ul class="section"><li><a href="../format/theme/index-hbs.html"><strong>3.3.1.</strong> index.hbs</a></li><li><a href="../format/theme/syntax-highlighting.html"><strong>3.3.2.</strong> Syntax highlighting</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>SUMMARY.md</h1>
<p>The summary file is used by mdBook to know what chapters to include,
in what order they should appear, what their hierarchy is and where the source files are.
Without this file, there is no book.</p>
<p>Even though <code>SUMMARY.md</code> is a markdown file, the formatting is very strict to
allow for easy parsing. Let's see how you should format your <code>SUMMARY.md</code> file.</p>
<h4>Allowed elements</h4>
<ol>
<li>
<p><strong><em>Title</em></strong> It's common practice to begin with a title, generally
<code class="language-markdown"># Summary</code>.
But it is not mandatory, the parser just ignores it. So you can too
if you feel like it.</p>
</li>
<li>
<p><strong><em>list link</em></strong> the other elements have to be list elements in form of a link</p>
<pre><code class="language-markdown">- [Title of the Chapter](relative/path/to/markdown.md)
</code></pre>
<p>You can either use <code>-</code> or <code>*</code> to indicate a list. The lists can be nested,
resulting in a nice hierarchy (chapters, sub-chapters, etc.)</p>
</li>
</ol>
<p>All other elements are unsupported and will be ignored at best or result in an error.</p>
<h4>not yet implemented</h4>
<p>In the feature I would like to add support for links without the need to be list elements
at the root level to add chapters that don't need numbering, like an index, appendix,
contributor list, introduction, foreword, etc.</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/format.html" class="nav-chapters previous">
<i class="fa fa-angle-left"></i>
</a>
<!-- -->
<!-- -->
<a href="../format/config.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

@ -7,15 +7,15 @@
<meta name="description" content="{% block description %}{% endblock %}"> <meta name="description" content="{% block description %}{% endblock %}">
<meta name="viewport" content="width=device-width, initial-scale=1"> <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 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 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="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"> <link rel="stylesheet" href="../../highlight.css" media="screen" title="no title" charset="utf-8">
</head> </head>
<body> <body>
<div id="sidebar" class="sidebar"> <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> <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><a href="../../format/format.html"><strong>3.</strong> Format</a></li><li><ul class="section"><li><a href="../../format/summary.html"><strong>3.1.</strong> SUMMARY.md</a></li><li><a href="../../format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="../../format/theme/theme.html"><strong>3.3.</strong> Theme</a></li><li><ul class="section"><li><a href="../../format/theme/index-hbs.html"class="active"><strong>3.3.1.</strong> index.hbs</a></li><li><a href="../../format/theme/syntax-highlighting.html"><strong>3.3.2.</strong> Syntax highlighting</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div> </div>
<div id="page-wrapper" class="page-wrapper"> <div id="page-wrapper" class="page-wrapper">
@ -27,32 +27,12 @@
</div> </div>
<div id="content" class="content"> <div id="content" class="content">
<h1>Theme</h1> <h1>index.hbs</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 <p><code>index.hbs</code> is the handlebars template that is used to render the book.
included in the mdBook binary.</p> The markdown files are processed to html and then injected in that template.</p>
<p>But the theme is totally customizable, you can replace every file from the theme by your own by adding a <p>If you want to change the layout or style of your book, chances are that you will
<code>theme</code> directory in your source folder. Create a new file with the name of the file you want to overwrite have to modify this template a little bit. Here is what you need to know.</p>
and now that file will be used instead of the default file.</p> <h2>Data</h2>
<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 modified theme.
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;. <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> In the handlebars template you can access this information by using</p>
<pre><code class="language-handlebars">{{name_of_property}} <pre><code class="language-handlebars">{{name_of_property}}
@ -83,7 +63,7 @@ Since the original directory structure is maintained, it is useful to prepend re
<p>containing all the chapters of the book. It is used for example to construct the table of contents (sidebar).</p> <p>containing all the chapters of the book. It is used for example to construct the table of contents (sidebar).</p>
</li> </li>
</ul> </ul>
<h3>Helpers</h3> <h2>Handlebars Helpers</h2>
<p>In addition to the properties you can access, there are some handlebars helpers at your disposal.</p> <p>In addition to the properties you can access, there are some handlebars helpers at your disposal.</p>
<ol> <ol>
<li> <li>
@ -135,7 +115,7 @@ and I will consider it.</p>
alternative until I find a way to do it in the template alternative until I find a way to do it in the template
--> -->
<a href="../format/config.html" class="nav-chapters previous"> <a href="../../format/theme/theme.html" class="nav-chapters previous">
<i class="fa fa-angle-left"></i> <i class="fa fa-angle-left"></i>
</a> </a>
@ -143,12 +123,16 @@ and I will consider it.</p>
<!-- --> <!-- -->
<a href="../../format/theme/syntax-highlighting.html" class="nav-chapters next">
<i class="fa fa-angle-right"></i>
</a>
<!-- --> <!-- -->
</div> </div>
<script src="http://code.jquery.com/jquery-2.1.4.min.js"></script> <script src="http://code.jquery.com/jquery-2.1.4.min.js"></script>
<script src="../highlight.js"></script> <script src="../../highlight.js"></script>
<script src="../book.js"></script> <script src="../../book.js"></script>
</body> </body>
</html> </html>

View File

@ -0,0 +1,78 @@
<!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><a href="../../format/format.html"><strong>3.</strong> Format</a></li><li><ul class="section"><li><a href="../../format/summary.html"><strong>3.1.</strong> SUMMARY.md</a></li><li><a href="../../format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="../../format/theme/theme.html"><strong>3.3.</strong> Theme</a></li><li><ul class="section"><li><a href="../../format/theme/index-hbs.html"><strong>3.3.1.</strong> index.hbs</a></li><li><a href="../../format/theme/syntax-highlighting.html"class="active"><strong>3.3.2.</strong> Syntax highlighting</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>Syntax Highlighting</h1>
<p>For syntax highlighting I use <a href="https://highlightjs.org">Highlight.js</a> with a custom theme.</p>
<p>Automatic language detection has been turned off, so you will probably want to
specify the programming language you use like this</p>
<pre class="language-markdown"><code class="language-markdown">```rust
fn main() {
// Some code
}
```</code></pre>
<h2>Improve default theme</h2>
<p>If you think the default theme doesn't look quite right for a specific language, or could be improved.
Feel free to <a href="https://github.com/azerupi/mdBook/issues">submit a new issue</a> explaining what you have in mind and I will take a look at it.</p>
<p>You could also create a pull-request with the proposed improvements.</p>
<p>Overall the theme should be light and sober, without to many flashy colors.</p>
<h2>Custom theme</h2>
<p>Like the rest of the theme, the files used for syntax highlighting can be overwritten with your own.</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>If you want to use another theme for <code>highlight.js</code> download it from their website, or make it yourself,
rename it to <code>highlight.css</code> and put it in <code>src/theme</code> (or the equivalent if you changed your source folder)</p>
<p>Now your theme will be used instead of the default theme.</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/theme/index-hbs.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,73 @@
<!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><a href="../../format/format.html"><strong>3.</strong> Format</a></li><li><ul class="section"><li><a href="../../format/summary.html"><strong>3.1.</strong> SUMMARY.md</a></li><li><a href="../../format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="../../format/theme/theme.html"class="active"><strong>3.3.</strong> Theme</a></li><li><ul class="section"><li><a href="../../format/theme/index-hbs.html"><strong>3.3.1.</strong> index.hbs</a></li><li><a href="../../format/theme/syntax-highlighting.html"><strong>3.3.2.</strong> Syntax highlighting</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>
</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>
<!-- -->
<!-- -->
<a href="../../format/theme/index-hbs.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

@ -13,6 +13,7 @@
/* Inline code */ /* Inline code */
:not(pre) > .hljs { :not(pre) > .hljs {
display: inline-block; display: inline-block;
vertical-align: middle;
padding: 0.1em 0.3em; padding: 0.1em 0.3em;
border-radius: 3px; border-radius: 3px;
} }
@ -61,7 +62,6 @@
.hljs-string, .hljs-string,
.hljs-value, .hljs-value,
.hljs-inheritance, .hljs-inheritance,
.hljs-header,
.ruby .hljs-symbol, .ruby .hljs-symbol,
.xml .hljs-cdata { .xml .hljs-cdata {
color: #2a9292; color: #2a9292;
@ -100,3 +100,16 @@
.xml .hljs-cdata { .xml .hljs-cdata {
opacity: 0.5; opacity: 0.5;
} }
/* markdown */
.hljs-header {
color: #A30000;
}
.hljs-link_label {
color: #33CCCC;
}
.hljs-link_url {
color: #CC66FF;
}

View File

@ -15,7 +15,7 @@
<body> <body>
<div id="sidebar" class="sidebar"> <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><li><a href="format/theme.html"><strong>3.3.</strong> Theme</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><a href="format/format.html"><strong>3.</strong> Format</a></li><li><ul class="section"><li><a href="format/summary.html"><strong>3.1.</strong> SUMMARY.md</a></li><li><a href="format/config.html"><strong>3.2.</strong> Configuration</a></li><li><a href="format/theme/theme.html"><strong>3.3.</strong> Theme</a></li><li><ul class="section"><li><a href="format/theme/index-hbs.html"><strong>3.3.1.</strong> index.hbs</a></li><li><a href="format/theme/syntax-highlighting.html"><strong>3.3.2.</strong> Syntax highlighting</a></li></ul><li><strong>4.</strong> Rust Library</li></ul>
</div> </div>
<div id="page-wrapper" class="page-wrapper"> <div id="page-wrapper" class="page-wrapper">

View File

@ -4,8 +4,10 @@
- [Command Line Tool](cli/cli-tool.md) - [Command Line Tool](cli/cli-tool.md)
- [init](cli/init.md) - [init](cli/init.md)
- [build](cli/build.md) - [build](cli/build.md)
- [Format]() - [Format](format/format.md)
- [SUMMARY.md]() - [SUMMARY.md](format/summary.md)
- [Configuration](format/config.md) - [Configuration](format/config.md)
- [Theme](format/theme.md) - [Theme](format/theme/theme.md)
- [index.hbs](format/theme/index-hbs.md)
- [Syntax highlighting](format/theme/syntax-highlighting.md)
- [Rust Library]() - [Rust Library]()

View File

@ -25,7 +25,7 @@ The `book` directory is where your book is rendered. All the output is ready to
to a serer to be seen by the internet. to a serer to be seen by the internet.
The `SUMMARY.md` file is the most important file, it's the skeleton of your book. The `SUMMARY.md` file is the most important file, it's the skeleton of your book.
It's so important that it has it's own [chapter](). It's so important that it has it's own [chapter](../format/summary.html).
#### Specify a directory #### Specify a directory

View File

@ -0,0 +1,8 @@
# Format
In this section you will learn how to:
- Structure your book correctly
- Format your `SUMMARY.md` file
- Configure your book using `book.json`
- Customize your theme

View File

@ -0,0 +1,30 @@
# SUMMARY.md
The summary file is used by mdBook to know what chapters to include,
in what order they should appear, what their hierarchy is and where the source files are.
Without this file, there is no book.
Even though `SUMMARY.md` is a markdown file, the formatting is very strict to
allow for easy parsing. Let's see how you should format your `SUMMARY.md` file.
#### Allowed elements
1. ***Title*** It's common practice to begin with a title, generally
<code class="language-markdown"># Summary</code>.
But it is not mandatory, the parser just ignores it. So you can too
if you feel like it.
2. ***list link*** the other elements have to be list elements in form of a link
```markdown
- [Title of the Chapter](relative/path/to/markdown.md)
```
You can either use `-` or `*` to indicate a list. The lists can be nested,
resulting in a nice hierarchy (chapters, sub-chapters, etc.)
All other elements are unsupported and will be ignored at best or result in an error.
#### not yet implemented
In the feature I would like to add support for links without the need to be list elements
at the root level to add chapters that don't need numbering, like an index, appendix,
contributor list, introduction, foreword, etc.

View File

@ -1,40 +1,12 @@
# Theme # index.hbs
The default renderer uses a [handlebars](http://handlebarsjs.com/) template to render your markdown files in and comes with a default theme `index.hbs` is the handlebars template that is used to render the book.
included in the mdBook binary. The markdown files are processed to html and then injected in that template.
But the theme is totally customizable, you can replace every file from the theme by your own by adding a If you want to change the layout or style of your book, chances are that you will
`theme` directory in your source folder. Create a new file with the name of the file you want to overwrite have to modify this template a little bit. Here is what you need to know.
and now that file will be used instead of the default file.
Here are the files you can overwrite: ## Data
- ***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 modified theme.
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". A lot of data is exposed to the handlebars template with the "context".
In the handlebars template you can access this information by using In the handlebars template you can access this information by using
@ -60,7 +32,7 @@ Since the original directory structure is maintained, it is useful to prepend re
``` ```
containing all the chapters of the book. It is used for example to construct the table of contents (sidebar). containing all the chapters of the book. It is used for example to construct the table of contents (sidebar).
### Helpers ## Handlebars Helpers
In addition to the properties you can access, there are some handlebars helpers at your disposal. In addition to the properties you can access, there are some handlebars helpers at your disposal.

View File

@ -0,0 +1,33 @@
# Syntax Highlighting
For syntax highlighting I use [Highlight.js](https://highlightjs.org) with a custom theme.
Automatic language detection has been turned off, so you will probably want to
specify the programming language you use like this
<pre class="language-markdown"><code class="language-markdown">```rust
fn main() {
// Some code
}
```</code></pre>
## Improve default theme
If you think the default theme doesn't look quite right for a specific language, or could be improved.
Feel free to [submit a new issue](https://github.com/azerupi/mdBook/issues) explaining what you have in mind and I will take a look at it.
You could also create a pull-request with the proposed improvements.
Overall the theme should be light and sober, without to many flashy colors.
## Custom theme
Like the rest of the theme, the files used for syntax highlighting can be overwritten with your own.
- ***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.
If you want to use another theme for `highlight.js` download it from their website, or make it yourself,
rename it to `highlight.css` and put it in `src/theme` (or the equivalent if you changed your source folder)
Now your theme will be used instead of the default theme.

View File

@ -0,0 +1,18 @@
# 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`.

View File

@ -13,6 +13,7 @@
/* Inline code */ /* Inline code */
:not(pre) > .hljs { :not(pre) > .hljs {
display: inline-block; display: inline-block;
vertical-align: middle;
padding: 0.1em 0.3em; padding: 0.1em 0.3em;
border-radius: 3px; border-radius: 3px;
} }
@ -61,7 +62,6 @@
.hljs-string, .hljs-string,
.hljs-value, .hljs-value,
.hljs-inheritance, .hljs-inheritance,
.hljs-header,
.ruby .hljs-symbol, .ruby .hljs-symbol,
.xml .hljs-cdata { .xml .hljs-cdata {
color: #2a9292; color: #2a9292;
@ -100,3 +100,16 @@
.xml .hljs-cdata { .xml .hljs-cdata {
opacity: 0.5; opacity: 0.5;
} }
/* markdown */
.hljs-header {
color: #A30000;
}
.hljs-link_label {
color: #33CCCC;
}
.hljs-link_url {
color: #CC66FF;
}