Added some chapters for the documentation #30 + tweaked the syntax highlighting theme
This commit is contained in:
Mathieu David
parent
58d18d467c
commit
991ccb5495
|
|
@ -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">
|
||||||
|
|
|
||||||
|
|
@ -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>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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">
|
||||||
|
|
|
||||||
|
|
@ -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>
|
||||||
|
|
|
||||||
|
|
@ -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>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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>
|
||||||
|
|
@ -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>
|
||||||
|
|
@ -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 "context".
|
<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>
|
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>
|
||||||
|
|
@ -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>
|
||||||
|
|
@ -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>
|
||||||
|
|
@ -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;
|
||||||
|
}
|
||||||
|
|
|
||||||
|
|
@ -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">
|
||||||
|
|
|
||||||
|
|
@ -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]()
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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.
|
||||||
|
|
@ -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.
|
||||||
|
|
||||||
|
|
@ -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.
|
||||||
|
|
@ -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`.
|
||||||
|
|
@ -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;
|
||||||
|
}
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue