From 991ccb54952004b4dd5e9c1fb33c6409913355ad Mon Sep 17 00:00:00 2001 From: Mathieu David Date: Wed, 5 Aug 2015 20:36:21 +0200 Subject: [PATCH] Added some chapters for the documentation #30 + tweaked the syntax highlighting theme --- book-example/book/README.html | 2 +- book-example/book/cli/build.html | 4 +- book-example/book/cli/cli-tool.html | 2 +- book-example/book/cli/init.html | 4 +- book-example/book/format/config.html | 6 +- book-example/book/format/format.html | 67 +++++++++++++++ book-example/book/format/summary.html | 86 +++++++++++++++++++ .../{theme.html => theme/index-hbs.html} | 50 ++++------- .../format/theme/syntax-highlighting.html | 78 +++++++++++++++++ book-example/book/format/theme/theme.html | 73 ++++++++++++++++ book-example/book/highlight.css | 15 +++- book-example/book/index.html | 2 +- book-example/src/SUMMARY.md | 8 +- book-example/src/cli/init.md | 2 +- book-example/src/format/format.md | 8 ++ book-example/src/format/summary.md | 30 +++++++ .../format/{theme.md => theme/index-hbs.md} | 42 ++------- .../src/format/theme/syntax-highlighting.md | 33 +++++++ book-example/src/format/theme/theme.md | 18 ++++ src/theme/highlight.css | 15 +++- 20 files changed, 461 insertions(+), 84 deletions(-) create mode 100644 book-example/book/format/format.html create mode 100644 book-example/book/format/summary.html rename book-example/book/format/{theme.html => theme/index-hbs.html} (61%) create mode 100644 book-example/book/format/theme/syntax-highlighting.html create mode 100644 book-example/book/format/theme/theme.html create mode 100644 book-example/src/format/format.md create mode 100644 book-example/src/format/summary.md rename book-example/src/format/{theme.md => theme/index-hbs.md} (60%) create mode 100644 book-example/src/format/theme/syntax-highlighting.md create mode 100644 book-example/src/format/theme/theme.md 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 @@
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 @@
@@ -59,7 +59,7 @@ current working directory.

- 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 @@
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 @@
@@ -45,7 +45,7 @@ configuration files, etc.

The book directory is where your book is rendered. All the output is ready to be uploaded 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. -It's so important that it has it's own chapter.

+It's so important that it has it's own chapter.

Specify a directory

When using the init command, you can also specify a directory, instead of using the current directory, by appending a path to the command:

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 @@
@@ -50,7 +50,7 @@ alternative until I find a way to do it in the template --> - @@ -58,7 +58,7 @@ - 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 @@ + + + + + mdBook Documentation + + + + + + + + + + + + + +
+ +
+ + +
+

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
    • +
+ +
+
+ + + + + + + + + + + + + +
+ + + + + + 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 @@ + + + + + mdBook Documentation + + + + + + + + + + + + + +
+ +
+ + +
+

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 +# Summary. +But it is not mandatory, the parser just ignores it. So you can too +if you feel like it.

    +
    2. +
  2. +

    list link the other elements have to be list elements in form of a link

    +
    - [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.)

    +
    3. +
+

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.

+ +
+
+ + + + + + + + + + + + + +
+ + + + + + diff --git a/book-example/book/format/theme.html b/book-example/book/format/theme/index-hbs.html similarity index 61% rename from book-example/book/format/theme.html rename to 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 @@ - + - +
@@ -27,32 +27,12 @@
-

Theme

-

The default renderer uses a handlebars template to render your markdown files in and comes with a default theme -included in the mdBook binary.

-

But the theme is totally customizable, you can replace every file from the theme by your own by adding a -theme directory in your source folder. Create a new file with the name of the file you want to overwrite -and now that file will be used instead of the default file.

-

Here are the files you can overwrite:

-
    -
  • index.hbs is the handlebars template.
    • -
  • book.css is the style used in the output. If you want to change the design of your book, this is probably the file you want to modify. Sometimes in conjunction with index.hbs when you want to radically change the layout.
    • -
  • book.js is mostly used to add client side functionality.
    • -
-

Note:

-

When you overwrite a file, it is possible that you break some functionality. Therefore I recommend to use the file from the default theme as template and only add / modify what you need. In the future you will be able to copy the default theme into your source directory automatically by using mdbook init --theme.

-

Syntax Highlighting

-

For syntax highlighting I use Highlight.js 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

-
```rust
-
-

Handlebars

-

Data

+

index.hbs

+

index.hbs is the handlebars template that is used to render the book. +The markdown files are processed to html and then injected in that template.

+

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.

+

Data

A lot of data is exposed to the handlebars template with the "context". In the handlebars template you can access this information by using

{{name_of_property}}
@@ -83,7 +63,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).

 
 
-
Helpers

+
Handlebars Helpers

 
In addition to the properties you can access, there are some handlebars helpers at your disposal.

 
    
 
  1. 
@@ -135,7 +115,7 @@ and I will consider it.
    
                 alternative until I find a way to do it in the template
             -->
             
-                
             
@@ -143,12 +123,16 @@ and I will consider it.
    
 
             
             
+                
+
- - + + 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 @@ + + + + + mdBook Documentation + + + + + + + + + + + + + +
+ +
+ + +
+

Syntax Highlighting

+

For syntax highlighting I use Highlight.js 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

+
```rust
+fn main() {
+    // Some code
+}
+```
+

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 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.

+ +
+
+ + + + + + + + + + + +
+ + + + + + diff --git a/book-example/book/format/theme/theme.html b/book-example/book/format/theme/theme.html new file mode 100644 index 00000000..42c53e6e --- /dev/null +++ b/book-example/book/format/theme/theme.html @@ -0,0 +1,73 @@ + + + + + mdBook Documentation + + + + + + + + + + + + + +
+ +
+ + +
+

Theme

+

The default renderer uses a handlebars 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.

+ +
+
+ + + + + + + + + + + + + +
+ + + + + + diff --git a/book-example/book/highlight.css b/book-example/book/highlight.css index 0b9578c3..616dba0d 100644 --- a/book-example/book/highlight.css +++ b/book-example/book/highlight.css @@ -13,6 +13,7 @@ /* Inline code */ :not(pre) > .hljs { display: inline-block; + vertical-align: middle; padding: 0.1em 0.3em; border-radius: 3px; } @@ -61,7 +62,6 @@ .hljs-string, .hljs-value, .hljs-inheritance, -.hljs-header, .ruby .hljs-symbol, .xml .hljs-cdata { color: #2a9292; @@ -100,3 +100,16 @@ .xml .hljs-cdata { opacity: 0.5; } + +/* markdown */ +.hljs-header { + color: #A30000; +} + +.hljs-link_label { + color: #33CCCC; +} + +.hljs-link_url { + color: #CC66FF; +} diff --git a/book-example/book/index.html b/book-example/book/index.html index 5dfc8bf9..0b7cfb17 100644 --- a/book-example/book/index.html +++ b/book-example/book/index.html @@ -15,7 +15,7 @@
diff --git a/book-example/src/SUMMARY.md b/book-example/src/SUMMARY.md index 8d9889ef..786d17f4 100644 --- a/book-example/src/SUMMARY.md +++ b/book-example/src/SUMMARY.md @@ -4,8 +4,10 @@ - [Command Line Tool](cli/cli-tool.md) - [init](cli/init.md) - [build](cli/build.md) -- [Format]() - - [SUMMARY.md]() +- [Format](format/format.md) + - [SUMMARY.md](format/summary.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]() diff --git a/book-example/src/cli/init.md b/book-example/src/cli/init.md index 23d272ce..ee9d0f67 100644 --- a/book-example/src/cli/init.md +++ b/book-example/src/cli/init.md @@ -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. 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 diff --git a/book-example/src/format/format.md b/book-example/src/format/format.md new file mode 100644 index 00000000..fe4cda8f --- /dev/null +++ b/book-example/src/format/format.md @@ -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 diff --git a/book-example/src/format/summary.md b/book-example/src/format/summary.md new file mode 100644 index 00000000..691301b7 --- /dev/null +++ b/book-example/src/format/summary.md @@ -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 + # Summary. + 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. diff --git a/book-example/src/format/theme.md b/book-example/src/format/theme/index-hbs.md similarity index 60% rename from book-example/src/format/theme.md rename to book-example/src/format/theme/index-hbs.md index 8cdff1b7..106d6fcf 100644 --- a/book-example/src/format/theme.md +++ b/book-example/src/format/theme/index-hbs.md @@ -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 -included in the mdBook binary. +`index.hbs` is the handlebars template that is used to render the book. +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 -`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. +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. -Here are the files you can overwrite: - -- ***index.hbs*** is the handlebars template. -- ***book.css*** is the style used in the output. If you want to change the design of your book, this is probably the file you want to modify. Sometimes in conjunction with `index.hbs` when you want to radically change the layout. -- ***book.js*** is mostly used to add client side functionality. - -**Note:** - -When you overwrite a file, it is possible that you break some functionality. Therefore I recommend to use the file from the default theme as template and only add / modify what you need. In the future you will be able to copy the default theme into your source directory automatically by using `mdbook init --theme`. - -### Syntax Highlighting - -For syntax highlighting I use [Highlight.js](https://highlightjs.org) with 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 +## Data A lot of data is exposed to the handlebars template with the "context". In the handlebars template you can access this information by using @@ -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). -### Helpers +## Handlebars Helpers In addition to the properties you can access, there are some handlebars helpers at your disposal. diff --git a/book-example/src/format/theme/syntax-highlighting.md b/book-example/src/format/theme/syntax-highlighting.md new file mode 100644 index 00000000..a5f1e197 --- /dev/null +++ b/book-example/src/format/theme/syntax-highlighting.md @@ -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 + +
```rust
+fn main() {
+    // Some code
+}
+```
+ +## 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. diff --git a/book-example/src/format/theme/theme.md b/book-example/src/format/theme/theme.md new file mode 100644 index 00000000..7afceff8 --- /dev/null +++ b/book-example/src/format/theme/theme.md @@ -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`. diff --git a/src/theme/highlight.css b/src/theme/highlight.css index 0b9578c3..616dba0d 100644 --- a/src/theme/highlight.css +++ b/src/theme/highlight.css @@ -13,6 +13,7 @@ /* Inline code */ :not(pre) > .hljs { display: inline-block; + vertical-align: middle; padding: 0.1em 0.3em; border-radius: 3px; } @@ -61,7 +62,6 @@ .hljs-string, .hljs-value, .hljs-inheritance, -.hljs-header, .ruby .hljs-symbol, .xml .hljs-cdata { color: #2a9292; @@ -100,3 +100,16 @@ .xml .hljs-cdata { opacity: 0.5; } + +/* markdown */ +.hljs-header { + color: #A30000; +} + +.hljs-link_label { + color: #33CCCC; +} + +.hljs-link_url { + color: #CC66FF; +}