aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.gitignore1
-rw-r--r--README.md17
-rw-r--r--book.toml8
3 files changed, 26 insertions, 0 deletions
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..7585238
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+book
diff --git a/README.md b/README.md
index 4bd06be..a5b2c9d 100644
--- a/README.md
+++ b/README.md
@@ -5,3 +5,20 @@ This repo contains documentation around the [Northstar mod](https://github.com/R
The `docs/` directory contains the content synchronised to the [GitBook Wiki page](https://r2northstar.gitbook.io/).
Use this repo to perform pull requests and open issues to request changes to the wiki content.
+
+## Building locally
+
+Unfortunately, [GitBook](https://www.gitbook.com/) does not offer a way to work and preview edited content locally.
+
+However, under the hood GitBook just uses [Markdown](https://www.markdownguide.org/) files that can be edited using any text editor.
+They can also be previewed to some degree on GitHub directly.
+
+### mdBook
+
+When working locally, [`mdBook`](https://rust-lang.github.io/mdBook/) can be used to render previews by simply running `mdbook serve`.
+Note that GitBook has a custom extended markdown syntax that is not supported by mdBook but using mdBook results in a rendered version that is good enough to verify the correctness of most changes.
+
+To install mdBook use the following link if:
+
+- [you have Rust toolchain installed](https://rust-lang.github.io/mdBook/guide/installation.html#build-from-source-using-rust)
+- [you **DON'T** have Rust toolchain installed](https://rust-lang.github.io/mdBook/guide/installation.html#pre-compiled-binaries)
diff --git a/book.toml b/book.toml
new file mode 100644
index 0000000..b788c8a
--- /dev/null
+++ b/book.toml
@@ -0,0 +1,8 @@
+# This file configures `mdbook` which is used for rendering wiki locally
+# See the main README.md for more info
+
+[book]
+language = "en"
+multilingual = false
+src = "docs"
+title = "Northstar Wiki"