diff options
author | Mathieu David <mathieudavid@mathieudavid.org> | 2015-08-05 20:36:21 +0200 |
---|---|---|
committer | Mathieu David <mathieudavid@mathieudavid.org> | 2015-08-05 20:36:21 +0200 |
commit | 991ccb54952004b4dd5e9c1fb33c6409913355ad (patch) | |
tree | 36df588a6478b95b64010419d3c5f14670de5376 | |
parent | 58d18d467cc015a06cbc4e6b59a5abcdafc3a523 (diff) |
Added some chapters for the documentation #30 + tweaked the syntax highlighting theme
20 files changed, 461 insertions, 84 deletions
diff --git a/book-example/book/README.html b/book-example/book/README.html index 5dfc8bf9..0b7cfb17 100644 --- a/book-example/book/README.html +++ b/book-example/book/README.html @@ -15,7 +15,7 @@ <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><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 id="page-wrapper" class="page-wrapper"> diff --git a/book-example/book/cli/build.html b/book-example/book/cli/build.html index 9b754e6d..8696d230 100644 --- a/book-example/book/cli/build.html +++ b/book-example/book/cli/build.html @@ -15,7 +15,7 @@ <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><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 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> </a> diff --git a/book-example/book/cli/cli-tool.html b/book-example/book/cli/cli-tool.html index d7d1b2e9..e44bb87b 100644 --- a/book-example/book/cli/cli-tool.html +++ b/book-example/book/cli/cli-tool.html @@ -15,7 +15,7 @@ <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><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 id="page-wrapper" class="page-wrapper"> diff --git a/book-example/book/cli/init.html b/book-example/book/cli/init.html index 63e0d432..1266d070 100644 --- a/book-example/book/cli/init.html +++ b/book-example/book/cli/init.html @@ -15,7 +15,7 @@ <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><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 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 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. -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> <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> diff --git a/book-example/book/format/config.html b/book-example/book/format/config.html index 9c20da68..840d296b 100644 --- a/book-example/book/format/config.html +++ b/book-example/book/format/config.html @@ -15,7 +15,7 @@ <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><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 id="page-wrapper" class="page-wrapper"> @@ -50,7 +50,7 @@ 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> </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> </a> diff --git a/book-example/book/format/format.html b/book-example/book/format/format.html new file mode 100644 index 00000000..fd49bc56 --- /dev/null +++ b/book-example/book/format/format.html @@ -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> diff --git a/book-example/book/format/summary.html b/book-example/book/format/summary.html new file mode 100644 index 00000000..7b1545fe --- /dev/null +++ b/book-example/book/format/summary.html @@ -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> diff --git a/book-example/book/format/theme.html b/book-example/book/format/theme/index-hbs.html index 5e08d08f..80e4290c 100644 --- a/book-example/book/format/theme.html +++ b/book-example/book/format/theme/index-hbs.html @@ -7,15 +7,15 @@ <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 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"> + <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> + <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 id="page-wrapper" class="page-wrapper"> @@ -27,32 +27,12 @@ </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 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> + <h1>index.hbs</h1> +<p><code>index.hbs</code> is the handlebars template that is used to render the book. +The markdown files are processed to html and then injected in that template.</p> +<p>If you want to change the layout or style of your book, chances are that you will +have to modify this template a little bit. Here is what you need to know.</p> +<h2>Data</h2> <p>A lot of data is exposed to the handlebars template with the "context". In the handlebars template you can access this information by using</p> <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> </li> </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> <ol> <li> @@ -135,7 +115,7 @@ and I will consider it.</p> 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> </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> <script src="http://code.jquery.com/jquery-2.1.4.min.js"></script> - <script src="../highlight.js"></script> - <script src="../book.js"></script> + <script src="../../highlight.js"></script> + <script src="../../book.js"></script> </body> </html> diff --git a/book-example/book/format/theme/syntax-highlighting.html b/book-example/book/format/theme/syntax-highlighting.html new file mode 100644 index 00000000..0d770451 --- /dev/null +++ b/book-example/book/format/theme/syntax-highlighting.html @@ -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> + + <!-- --> + + <!-- --> + |