Archives
/
mkbook
mirror of https://github.com/hamaluik/mkbook
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

updated docs, changed chapter index.md to README.md

Browse Source
master
Kenton Hamaluik 5 years ago
parent 628426bed9
commit bfdc237e9c
19 changed files with 81 additions and 75 deletions
Show Stats Download Patch File Download Diff File

2
docs-src/02-markdown/02-syntax-highlighting.md
Unescape Escape View File

@ -6,7 +6,7 @@ title = "Syntax Highlighting"
GFM syntax highlighting is also available by using fenced code tags with a label denoting the language, as such:
~~~md
~~~
```c++
#include <stdio>

17
docs-src/02-markdown/README.md
Unescape Escape View File

@ -0,0 +1,17 @@
---
title = "Markdown"
---
_mkbook_ relies pretty extensively on [Markdown](https://daringfireball.net/projects/markdown/) for its ease of use. If you're not familiar with _Markdown_, it is a simple markup language that is design to be easy to read and write in plain text, and then (relatively) easy for a computer to convert into other formats such as HTML or LaTeX.
The above paragraph looks like this:
```md
_mkbook_ relies pretty extensively on
[Markdown](https://daringfireball.net/projects/markdown/) for its ease of use.
If you're not familiar with _Markdown_, it is a simple markup language that is
design to be easy to read and write in plain text, and then (relatively) easy
for a computer to convert into other formats such as HTML or LaTeX.
```
_Markdown_ by itself isn't quite enough for most purposes, so _mkbook_ actually uses the _CommonMark_ spec with some additional extensions to make life easier.

5
docs-src/02-markdown/index.md
Unescape Escape View File

@ -1,5 +0,0 @@
---
title = "Markdown"
---
_mkbook_ relies pretty extensively on [Markdown](https://daringfireball.net/projects/markdown/) for its ease of use.

11
docs-src/04-structure.md
Unescape Escape View File

@ -59,15 +59,20 @@ unimplemented!()
## Documents
For now, _mkbook_ only works on a flat list of markdown files, with the intent of each markdown file being its own chapter. Subdirectories and files that don't end in a `.md` extension are completely ignored. The order of the book is based on the alphabetical order of the file names (actually it's based on Rust's [implementation of `PartialOrd` for str](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html#impl-PartialOrd%3Cstr%3E)). Thus, it is recommended to lay out your book chapters with manual numbering of the file names, as such:
_mkbook_ works on mostly a flat directory structure, however one level of sub-directories are supported in order to create sections within chapters. Files that don't end in a `.md` extension are completely ignored. Each `.md` file in the root source directly is it's own chapter. To create chapters with sub-sections, create a sub-directory in the root directory and then create a `README.md` file, which will become the root of the chapter, with all `.md` files in the sub-directory becoming sections in the chapter. The `title` in the `README.md` file's frontmatter will be used as the name of the chapter.
The order of the book is based on the alphabetical order of the file names (actually it's based on Rust's [implementation of `PartialOrd` for str](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html#impl-PartialOrd%3Cstr%3E)). Thus, it is recommended to lay out your book chapters with manual numbering of the file names, as such:
```
src/
├── mkbook.toml
├── 00-foreword.md
├── 01-introduction.md
├── 02-my-first-chapter.md
└── etc...
└── 02-my-first-chapter
├── index.md
├── 01-my-first-section.md
├── 02-my-second-section.md
└── etc...
```
An index and navigation will be automatically generated from these files, taking the information for each file from it's front-matter.

9
docs-src/06-how-it-works.md
Unescape Escape View File

@ -22,4 +22,11 @@ Markdown is formatted usiing [comrak](https://crates.io/crates/comrak) with some
## Syntax Highlighting
Code is syntax-highlighted using [syntect](https://crates.io/crates/syntect) with the default langauges and the `base16-eighties` colour scheme.
Code is syntax-highlighted using [syntect](https://crates.io/crates/syntect) with the default langauges and the `base16-eighties` colour scheme. Some additional languages above the base list supported by _syntect_ have been aded:
* `haxe`
* `hxml`
* `sass`
* `scss`
* `toml`

2
docs/01-introduction/index.html
Unescape Escape View File

@ -14,7 +14,7 @@
&lt;p&gt;This tool aims to work somewhat similarly to &lt;em&gt;mdbook&lt;&#x2f;em&gt;, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.&lt;&#x2f;p&gt;
" />
<meta property="book:author" content="Kenton Hamaluik" />
<meta property="book:release_date" content="2019-11-29T21:20:04.527238643+00:00" />
<meta property="book:release_date" content="2019-11-29T21:43:28.060984725+00:00" />
</head>
<body>
<nav class="big">

2
docs/02-markdown/01-commonmark.html
Unescape Escape View File

@ -14,7 +14,7 @@
&lt;p&gt;This tool aims to work somewhat similarly to &lt;em&gt;mdbook&lt;&#x2f;em&gt;, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.&lt;&#x2f;p&gt;
" />
<meta property="book:author" content="Kenton Hamaluik" />
<meta property="book:release_date" content="2019-11-29T21:20:04.527238643+00:00" />
<meta property="book:release_date" content="2019-11-29T21:43:28.060984725+00:00" />
</head>
<body>
<nav class="big">

4
docs/02-markdown/02-syntax-highlighting.html
Unescape Escape View File

@ -14,7 +14,7 @@
&lt;p&gt;This tool aims to work somewhat similarly to &lt;em&gt;mdbook&lt;&#x2f;em&gt;, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.&lt;&#x2f;p&gt;
" />
<meta property="book:author" content="Kenton Hamaluik" />
<meta property="book:release_date" content="2019-11-29T21:20:04.527238643+00:00" />
<meta property="book:release_date" content="2019-11-29T21:43:28.060984725+00:00" />
</head>
<body>
<nav class="big">
@ -105,7 +105,7 @@
<h1><a href="#syntax-highlighting" aria-hidden="true" class="anchor" id="headersyntax-highlighting"></a>Syntax Highlighting</h1>
<p>GFM syntax highlighting is also available by using fenced code tags with a label denoting the language, as such:</p>
<pre style="background-color:#2d2d2d;">
<span style="color:#d3d0c8;">```</span><span style="color:#f99157;">c</span><span style="color:#d3d0c8;">++
<span style="color:#d3d0c8;">```c++
</span><span style="color:#d3d0c8;">#include &lt;stdio&gt;
</span><span style="color:#d3d0c8;">
</span><span style="color:#d3d0c8;">int main() {

13
docs/02-markdown/index.html
Unescape Escape View File

@ -14,7 +14,7 @@
&lt;p&gt;This tool aims to work somewhat similarly to &lt;em&gt;mdbook&lt;&#x2f;em&gt;, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.&lt;&#x2f;p&gt;
" />
<meta property="book:author" content="Kenton Hamaluik" />
<meta property="book:release_date" content="2019-11-29T21:20:04.527238643+00:00" />
<meta property="book:release_date" content="2019-11-29T21:43:28.060984725+00:00" />
</head>
<body>
<nav class="big">
@ -102,7 +102,16 @@
</span>
</nav>
<article>
<p><em>mkbook</em> relies pretty extensively on <a href="https://daringfireball.net/projects/markdown/">Markdown</a> for its ease of use.</p>
<p><em>mkbook</em> relies pretty extensively on <a href="https://daringfireball.net/projects/markdown/">Markdown</a> for its ease of use. If you’re not familiar with <em>Markdown</em>, it is a simple markup language that is design to be easy to read and write in plain text, and then (relatively) easy for a computer to convert into other formats such as HTML or LaTeX.</p>
<p>The above paragraph looks like this:</p>
<pre style="background-color:#2d2d2d;">
<span style="font-style:italic;color:#cc99cc;">_mkbook_</span><span style="color:#d3d0c8;"> relies pretty extensively on
</span><span style="color:#f99157;">[Markdown](https://daringfireball.net/projects/markdown/)</span><span style="color:#d3d0c8;"> for its ease of use.
</span><span style="color:#d3d0c8;">If you&#39;re not familiar with </span><span style="font-style:italic;color:#cc99cc;">_Markdown_</span><span style="color:#d3d0c8;">, it is a simple markup language that is
</span><span style="color:#d3d0c8;">design to be easy to read and write in plain text, and then (relatively) easy
</span><span style="color:#d3d0c8;">for a computer to convert into other formats such as HTML or LaTeX.
</span></pre>
<p><em>Markdown</em> by itself isn’t quite enough for most purposes, so <em>mkbook</em> actually uses the <em>CommonMark</em> spec with some additional extensions to make life easier.</p>

2
docs/03-frontmatter/index.html
Unescape Escape View File

@ -14,7 +14,7 @@
&lt;p&gt;This tool aims to work somewhat similarly to &lt;em&gt;mdbook&lt;&#x2f;em&gt;, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.&lt;&#x2f;p&gt;
" />
<meta property="book:author" content="Kenton Hamaluik" />
<meta property="book:release_date" content="2019-11-29T21:20:04.527238643+00:00" />
<meta property="book:release_date" content="2019-11-29T21:43:28.060984725+00:00" />
</head>
<body>
<nav class="big">

12
docs/04-structure/index.html
Unescape Escape View File

@ -14,7 +14,7 @@
&lt;p&gt;This tool aims to work somewhat similarly to &lt;em&gt;mdbook&lt;&#x2f;em&gt;, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.&lt;&#x2f;p&gt;
" />
<meta property="book:author" content="Kenton Hamaluik" />
<meta property="book:release_date" content="2019-11-29T21:20:04.527238643+00:00" />
<meta property="book:release_date" content="2019-11-29T21:43:28.060984725+00:00" />
</head>
<body>
<nav class="big">
@ -161,14 +161,18 @@
<span style="color:#d3d0c8;">unimplemented!()
</span></pre>
<h2><a href="#documents" aria-hidden="true" class="anchor" id="headerdocuments"></a>Documents</h2>
<p>For now, <em>mkbook</em> only works on a flat list of markdown files, with the intent of each markdown file being its own chapter. Subdirectories and files that don’t end in a <code>.md</code> extension are completely ignored. The order of the book is based on the alphabetical order of the file names (actually it’s based on Rust’s <a href="https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html#impl-PartialOrd%3Cstr%3E">implementation of <code>PartialOrd</code> for str</a>). Thus, it is recommended to lay out your book chapters with manual numbering of the file names, as such:</p>
<p><em>mkbook</em> works on mostly a flat directory structure, however one level of sub-directories are supported in order to create sections within chapters. Files that don’t end in a <code>.md</code> extension are completely ignored. Each <code>.md</code> file in the root source directly is it’s own chapter. To create chapters with sub-sections, create a sub-directory in the root directory and then create a <code>README.md</code> file, which will become the root of the chapter, with all <code>.md</code> files in the sub-directory becoming sections in the chapter. The <code>title</code> in the <code>README.md</code> file’s frontmatter will be used as the name of the chapter.</p>
<p>The order of the book is based on the alphabetical order of the file names (actually it’s based on Rust’s <a href="https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html#impl-PartialOrd%3Cstr%3E">implementation of <code>PartialOrd</code> for str</a>). Thus, it is recommended to lay out your book chapters with manual numbering of the file names, as such:</p>
<pre style="background-color:#2d2d2d;">
<span style="color:#d3d0c8;">src/
</span><span style="color:#d3d0c8;">├── mkbook.toml
</span><span style="color:#d3d0c8;">├── 00-foreword.md
</span><span style="color:#d3d0c8;">├── 01-introduction.md
</span><span style="color:#d3d0c8;">├── 02-my-first-chapter.md
</span><span style="color:#d3d0c8;">└── etc...
</span><span style="color:#d3d0c8;">└── 02-my-first-chapter
</span><span style="color:#d3d0c8;"> ├── index.md
</span><span style="color:#d3d0c8;"> ├── 01-my-first-section.md
</span><span style="color:#d3d0c8;"> ├── 02-my-second-section.md
</span><span style="color:#d3d0c8;"> └── etc...
</span></pre>
<p>An index and navigation will be automatically generated from these files, taking the information for each file from it’s front-matter.</p>

2
docs/05-customization/index.html
Unescape Escape View File

@ -14,7 +14,7 @@
&lt;p&gt;This tool aims to work somewhat similarly to &lt;em&gt;mdbook&lt;&#x2f;em&gt;, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.&lt;&#x2f;p&gt;
" />
<meta property="book:author" content="Kenton Hamaluik" />
<meta property="book:release_date" content="2019-11-29T21:20:04.527238643+00:00" />
<meta property="book:release_date" content="2019-11-29T21:43:28.060984725+00:00" />
</head>
<body>
<nav class="big">

11
docs/06-how-it-works/index.html
Unescape Escape View File

@ -14,7 +14,7 @@
&lt;p&gt;This tool aims to work somewhat similarly to &lt;em&gt;mdbook&lt;&#x2f;em&gt;, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.&lt;&#x2f;p&gt;
" />
<meta property="book:author" content="Kenton Hamaluik" />
<meta property="book:release_date" content="2019-11-29T21:20:04.527238643+00:00" />
<meta property="book:release_date" content="2019-11-29T21:43:28.060984725+00:00" />
</head>
<body>
<nav class="big">
@ -106,7 +106,14 @@
<h2><a href="#markdown-formatting" aria-hidden="true" class="anchor" id="headermarkdown-formatting"></a>Markdown Formatting</h2>
<p>Markdown is formatted usiing <a href="https://crates.io/crates/comrak">comrak</a> with some specific options, see the <a href="02-markdown.html">Markdown chapter</a> for more information.</p>
<h2><a href="#syntax-highlighting" aria-hidden="true" class="anchor" id="headersyntax-highlighting"></a>Syntax Highlighting</h2>
<p>Code is syntax-highlighted using <a href="https://crates.io/crates/syntect">syntect</a> with the default langauges and the <code>base16-eighties</code> colour scheme.</p>
<p>Code is syntax-highlighted using <a href="https://crates.io/crates/syntect">syntect</a> with the default langauges and the <code>base16-eighties</code> colour scheme. Some additional languages above the base list supported by <em>syntect</em> have been aded:</p>
<ul>
<li><code>haxe</code></li>
<li><code>hxml</code></li>
<li><code>sass</code></li>
<li><code>scss</code></li>
<li><code>toml</code></li>
</ul>

4
docs/index.html
Unescape Escape View File

@ -14,13 +14,13 @@
&lt;p&gt;This tool aims to work somewhat similarly to &lt;em&gt;mdbook&lt;&#x2f;em&gt;, but is generally intended to be a more minimal alternative that is customized more towards my needs and desires than anything else.&lt;&#x2f;p&gt;
" />
<meta property="book:author" content="Kenton Hamaluik" />
<meta property="book:release_date" content="2019-11-29T21:20:04.527238643+00:00" />
<meta property="book:release_date" content="2019-11-29T21:43:28.060984725+00:00" />
</head>
<body class="toc">
<header>
<h1>The mkbook Book</h1>
<h2>by Kenton Hamaluik</h2>
<time datetime="2019-11-29T21:20:04.527238643+00:00">Nov 29, 2019</time>
<time datetime="2019-11-29T21:43:28.060984725+00:00">Nov 29, 2019</time>
</header>
<article>
<p><em>mkbook</em> is my simpler alternative to <a href="https://crates.io/crates/mdbook">mdbook</a> which is a great tool, but for which I really dislike some of the decisions they took, such as relying on javascript for highlighting and navigation, and including a lot of bells and whistles such as javascript-based search.</p>

2
docs/style.css
View File

File diff suppressed because one or more lines are too long

4
src/main.rs
Unescape Escape View File

@ -275,7 +275,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
// try to find a `chapter.toml` file and parse it to get the chapter's title, fall back to the directory
// name if we can't do that
let chapter_name = path.file_name().map(std::ffi::OsStr::to_str).flatten().unwrap_or_default();
let index_path = path.join("index.md");
let index_path = path.join("README.md");
let (front, contents) = if index_path.exists() {
let contents = fs::read_to_string(&index_path)?;
let (front, contents) = extract_frontmatter(&contents)?;
@ -303,7 +303,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
let name = path.file_stem().map(std::ffi::OsStr::to_str).flatten();
if name.is_none() { continue; }
let name = name.unwrap();
if name == "index" {
if name == "README" {
continue;
}

33
style/base.scss
Unescape Escape View File

@ -72,14 +72,14 @@ dl {
dt {
font-weight: 700;
margin: 0;
padding: 0 0.5em 0.25rem;
padding: 0 0.5rem 0.25rem;
border-right: 1px solid #dddddd;
text-align: right;
}
dd {
margin: 0;
padding: 0 0.5em 0.25rem;
padding: 0 0.5rem 0.25rem;
}
dt, dd {
@ -113,32 +113,3 @@ table {
vertical-align: top;
}
}
// sub-list numbering
// taken from: https://stackoverflow.com/a/26245056
ol {
list-style-type: none;
counter-reset: item;
margin: 0;
padding: 0;
}
ol > li {
display: table;
counter-increment: item;
margin-bottom: 0.6rem;
}
ol > li:before {
content: counters(item, ".") ". ";
display: table-cell;
padding-right: 0.6rem;
}
li ol > li {
margin: 0;
}
li ol > li:before {
content: counters(item, ".") " ";
}

13
style/layout.scss
Unescape Escape View File

@ -12,7 +12,8 @@ body {
nav.big {
background: #2c2c38;
padding: 0.5em 1em 1rem;
padding: 0.5rem 1rem 1rem;
max-width: 15rem;
display: flex;
flex-direction: column;
@ -62,7 +63,7 @@ body {
color: #eeeeee;
a {
text-decoration: none;
margin: 0 0 0.25em 0;
margin: 0 0 0.25rem 0;
color: #5babd1;
&:hover {
@ -83,10 +84,6 @@ body {
}
}
}
/*ol { counter-reset: item }
li{ display: block }
li:before { content: counters(item, ".") " "; counter-increment: item }*/
}
nav.small {
@ -144,7 +141,7 @@ body {
article {
max-width: 38rem;
padding: 0.5em 2em 0 2rem;
padding: 0.5rem 2rem 0 2rem;
>* {
max-width: 100%;
@ -199,7 +196,7 @@ body {
}
article {
padding: 1em 0.5em 0 0.5rem;
padding: 1rem 0.5rem 0 0.5rem;
}
}
}

8
style/toc.scss
Unescape Escape View File

@ -55,19 +55,13 @@ body.toc {
a {
text-decoration: none;
margin: 0 0 0.25em 0;
margin: 0 0 0.25rem 0;
color: #5babd1;
&:hover {
color: #cf5ccd;
}
}
ol {
li {
font-size: 1.25rem;
}
}
}
}

Write Preview
Loading…
Cancel
Save