Resiliate documentation
This book is written using a documentation system called Markdown Book. It uses Markdown to create content.
Please have a quick read of how we use markdown to write content. And then read [#anatomy-of-a-book){:target=_blank} section to get a basic understanding of how books are organized.
Markdown is a straightforward syntax that facilitates the formatting of text documents. It's particularly useful when creating and editing documentation files, such as those in an mdBook project. Markdown enables the addition of structure and style to plaintext content, all without the need for complex web coding languages. It's as simple as writing an email or a text message, yet it has the added capability to incorporate elements like headers, links, lists, and more. This simplicity and versatility make Markdown an ideal tool for creating and maintaining complex documentation in mdBook, even for those without a technical background.
In Markdown, you use the # symbol to create a heading. The number of # symbols you use should correspond to the heading level. For example, to create a heading level three (<h3>), you'd use three # symbols.
# Heading 1
## Heading 2
### Heading 3You can make text bold or italic.
- Bold:
**bold text** - Italic:
*italicized text*
Markdown supports ordered (numbered) and unordered (bulleted) lists.
- Unordered Lists: You can use
*,-, or+to create an unordered list.
* Item 1
* Item 2
* Item 3- Ordered Lists: You can create an ordered list by using numbers:
1. Item 1
2. Item 2
3. Item 3You can create an inline link by wrapping link text in brackets [ ], and then wrapping the URL in parentheses ( ).
[Visit GitHub!](www.github.com)You can use the following syntax to create an image:
You can create a code block by wrapping your code in triple backticks.
```
Code block goes here....
```
You can directly include HTML (HyperText Markup Language)—which is the standard markup language for creating web pages—directly into markdown. It describes the structure of a web page and it consists of a series of elements.
<h1>to<h6>: Define headings.<h1>defines the most important heading and<h6>defines the least important heading.<p>: Define a paragraph.<a>: Define a hyperlink.<img>: Define an image.<ul>: Define an unordered list.<ol>: Define an ordered list.<li>: Define a list item.
Here's a basic example of HTML:
<!DOCTYPE html>
<html>
<head>
<title>Page Title</title>
</head>
<body>
<h1>My First Heading</h1>
<p>My first paragraph.</p>
<a href="https://www.example.com">This is a link</a>
<img src="image.jpg" alt="Alt Text">
<ul>
<li>First item</li>
<li>Second item</li>
</ul>
</body>
</html>Remember, while Markdown files (.md) support HTML, it's best to use Markdown syntax whenever possible for simplicity and readability.
A book is built from several files which define the settings and layout of the book.
In the root of your book, there is a book.toml file which contains settings for describing how to build your book.
This is written in the TOML markup language.
The default settings are usually good enough to get you started.
A very basic book.toml can be as simple as this:
[book]
title = "My First Book"The next major part of a book is the summary file located at src/SUMMARY.md.
This file contains a list of all the chapters in the book.
Before a chapter can be viewed, it must be added to this list.
Here's a basic summary file with a few chapters:
# Summary
[Introduction](README.md)
- [My First Chapter](my-first-chapter.md)
- [Nested example](nested/README.md)
- [Sub-chapter](nested/sub-chapter.md)Try opening up src/SUMMARY.md in your editor and adding a few chapters.
If any of the chapter files do not exist, mdbook will automatically create them for you.
The content of your book is all contained in the src directory.
Each chapter is a separate Markdown file.
Typically, each chapter starts with a level 1 heading with the title of the chapter.
# My First Chapter
Fill out your content here.The precise layout of the files is up to you. The organization of the files will correspond to the HTML files generated, so keep in mind that the file layout is part of the URL of each chapter.
While the mdbook serve command is running, you can open any of the chapter files and start editing them.
Each time you save the file, mdbook will rebuild the book and refresh your web browser.
All other files in the src directory will be included in the output.
So if you have images or other static files, just include them somewhere in the src directory.
mdBook is a utility designed to create online books using Markdown syntax. It's an excellent tool for crafting documentation, tutorials, course materials, or any content that benefits from a structured, navigable, and customizable presentation.
Markdown is a lightweight markup language that allows you to add formatting elements to plaintext text documents. It's often used for formatting readme files, for writing messages in online discussion forums, and to create rich text using a plain text editor.
mdBook takes this a step further by providing additional features that enhance the functionality of standard Markdown:
- Integrated Search Support: This helps users find the information they need quickly.
- Syntax Highlighting: This provides color syntax highlighting for code blocks in many different languages.
- Customizable Themes: This allows you to modify the look and feel of your output.
- Preprocessors and Backends: These support extensions for custom syntax, content modification, and rendering output to multiple formats.
One of the powerful features of mdBook is the ability to include files in your book. This is done using the following syntax:
{{#include file.md}}The path to the file has to be relative from the current source file. So if the file is in src directory then an {{#include another-file.md}} will assume that another-file.md
is also in src directory.
{{#include file.md}}Often you only need a specific part of the file, e.g., relevant lines for an example. mdBook supports four different modes of partial includes:
{{#include file.rs:2}}
{{#include file.rs::10}}
{{#include file.rs:2:}}
{{#include file.rs:2:10}}The first command only includes the second line from the file. The second command includes all lines up to line 10. The third command includes all lines from line 2, and the last command includes the excerpt of the file consisting of lines 2 to 10.
To avoid breaking the book when modifying included files, we can also include a specific section using anchors instead of line numbers. An anchor is a pair of matching lines. The line beginning an anchor must match the regex ANCHOR: <NAME> + and similarly the ending line must match the regex ANCHOR_END: <NAME>
Then we can include that part in other files. (See src/includes.md in this repository for example of collected anchors) and how they are used elsewhere using {{#include includes.md:<NAME>}}
You can edit the Markdown files directly on GitHub using the online editing features. This allows you to make changes to the content without needing to clone the repository or set up any local development environment. Simply navigate to the file you want to edit, click the "Edit" button (represented by a pencil icon), make your changes, and then commit the changes directly to the branch.
Remember, the goal is to keep things simple. Start with basic Markdown syntax and gradually introduce more complex features as needed. Happy writing with mdBook!