Improve docs for 0.3 (fix #51) + changelog + make it nim v2.0 compatible

.gitattributes

@@ -0,0 +1 @@
+src/nimibook/assets/* linguist-vendored

.github/workflows/tests.yml

@@ -0,0 +1,31 @@
+name: Run tests
+on: 
+  push:
+    branches:
+      - main
+  pull_request:
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        nim:
+          - '1.6.x'
+          - 'stable'
+          - 'devel'
+      fail-fast: false
+    name: Nim ${{ matrix.nim }}
+    steps:
+      - uses: actions/checkout@v3
+      - uses: jiro4989/[email protected]
+        with:
+          nim-version: ${{ matrix.nim }}
+      - run: nimble -y install
+      - run: nimble test
+      - name: Test generation of nimibook documentation
+        run: nimble genbook
+      - name: Test example book
+        run: nimble test_example
+      - name: Clean example book
+        run: nimble clean_example
+

README.md

@@ -3,101 +3,124 @@
 **nimibook** is a port of [mdbook] to [Nim], powered by [nimib].
 Nimibook allows to create a nice looking book from nim code and markdown,
 making sure that nim code is running correctly and being able to incorporate code outputs in the final book.
-An example book is [nimibook documentation][nimibook] itself.
+An example book is [nimibook] documentation.
 
-[mdBook] is a command line tool and Rust crate to create books
-using Markdown (as by the CommonMark specification) files.
-It's very similar to [Gitbook], which is a command line tool (and Node.js library)
-for building beautiful books using GitHub/Git and Markdown (or AsciiDoc).
+> [mdBook] is a command line tool and Rust crate to create books
+> using Markdown (as by the CommonMark specification) files.
+> It's very similar to [Gitbook], which is a command line tool (and Node.js library)
+> for building beautiful books using GitHub/Git and Markdown (or AsciiDoc).
 
 [nimib] is a Nim library to convert your Nim code and its outputs to html documents.
 The html output can be easily customized thanks to [nim-mustache],
 and this is what allows it to use it to build nimibook.
 _nimib documents_ are normal nim files which use nimib library to produce an output document.
 
+One particular advantage of nimib is that it can incorporate interactive content
+taking advantage of nim's js backend.
+For the basic examples see
+[nimib interactivity doc](https://pietroppeter.github.io/nimib/interactivity.html).
+
 The Markdown dialect supported by both nimib and nimibook is the subset of [Github Flavored Markdown][GFM]
-provided by [nim-markdown]. For a quick reference of supported syntax see the [cheatsheet].
+provided by [nim-markdown]. For a quick reference of supported syntax see this [cheatsheet] (created with nimib).
+
+<!--refs-->
+[mdbook]: https://rust-lang.github.io/mdBook/index.html
+[Nim]: https://nim-lang.org/
+[nimib]: https://pietroppeter.github.io/nimib/
+[Gitbook]: https://github.com/GitbookIO/gitbook
+[nim-mustache]: https://github.com/soasme/nim-mustache
+[nimibook]: https://pietroppeter.github.io/nimibook/
+[GFM]: https://github.github.com/gfm/
+[nim-markdown]: https://github.com/soasme/nim-markdown
+[cheasheet]: https://pietroppeter.github.io/nimib/cheatsheet.html
+
+## Status
+
+Nimibook is actively maintained ([target issues for 2023](https://github.com/pietroppeter/nimibook/issues?q=is%3Aopen+is%3Aissue+label%3A2023H1%2C2023H2))
+and it provides the basic functionality
+needed to create a book with markdown and nimib sources.
+It still has some features missing from mdbook
+(see [this issue](https://github.com/pietroppeter/nimibook/issues/9#issuecomment-851989939)).
+
+To follow up on recent changes check the [changelog.md](changelog.md).
+
+## Example sites using nimibook
 
-### Status
+- [scinim/getting-started](https://scinim.github.io/getting-started/)
+- [moigagoo/norm](https://norm.nim.town)
+- [PhilippMDoerner/Snorlogue](https://philippmdoerner.github.io/Snorlogue/bookCompiled/)
 
-nimibook currently provides minimal functionality to create a book and support a local CLI mode.
+You are welcome to open a PR and add your site using nimibook here.
+
+## Features
+
+- table of contents in a collapsible sidebar
+- five themes (Light, Rust, Coal, Navy, Ayu)
+- buttons to next/previous pages
+- build multiple files in parallel
+- (optional) latex content with katex
+- (optional) link to github repo
+- (optional) link to track analytics with plausible analytics
 
 ## Installation
 
-To install Nimibook simply use : `nimble install nimibook`
+To install Nimibook: `nimble install nimibook`
 
-## Usage
+## How to setup your book with nimibook
 
-1. Write your content using [nimib] or simple markdown files in the `book` folder.
-   The basic template for an empty page is:
-```nim
-import nimib, nimibook
+Nimibook does not ([yet](https://github.com/pietroppeter/nimibook/issues/63)) provides an executable to manage your book, but it provides the basic building blocks to write your own.
 
-nbInit(theme = useNimibook)
-# content here
-nbSave
-```
+**1. example nbook.nim**: in a folder of your choice create a `nbook.nim` file with the following content:
 
-2. Use the Table of Content (ToC) DSL to link chapters to content in `nbook.nim`.
-Example : 
 ```nim
 import nimibook
 
-# Create a new book called "Dummy", whose content is in the folder "book"
-var book = newBookFromToc("Dummy Book", "book"):
-  # Create a new section called "Dummy", its content is the file "index.nim"
-  section("Dummy", "index"): # Note how the .nim extensions is optional
-    # Create a new entry called "Simple example", its content is the file "page_1.nim"
-    entry("Simple example", "page_1.nim")
+var book = initBookWithToc:
+  entry("Preface", "preface.md", numbered = false)
+  entry("Introduction", "intro.md")
+  section("Chapter 1", "chapter1/index.nim"):
+    entry("Content", "content.nim")
+    draft("Nothing yet")
+    section("Sub chapter", "no_ext"):
+      entry("and some more content", "more.md")
 
-# access to nimibook cli which will allow to build the book
 nimibookCli(book)
 ```
-See [nimibook] or [Nimibook repo](https://github.com/pietroppeter/nimibook
-) for more documentations and examples.
-
-3. Generate your very own CLI tools or use Nimble tasks with `nim c -d:release nbook.nim`.
-  * `./nbook init` to init your book structure. **This command must be ran at least once**. 
-  * `./nbook build` to build your book.
 
-4. Whenever your Table of Content changes (add/remove files, changes sections organization), recompile your `nbook` and run the `build` command : `nim c -d:release nbook.nim && ./nbook build`
-  * It is also doable in one command : `nim r -d:release nbook.nim build`
-  * You don't need to call the `init` command again.
-  * Rinse and repeat until your ToC is done ! Then you can just edit files and call `build` without recompiling.
+**2. write a TOC**: modify `nbook.nim` to specify
+the planned Table of Content (TOC) for your book.
 
-## Tips and Tricks 
+**3. nbook init**: running `nim r nbook init` (or compile `nbook` and run `nbook init`) will set up the book with:
+- a `nimib.toml` that contains the default configuration for the book
+- a `book` folder that contains sources for all chapters mentioned in the TOC. Note that `.nim` files already contain default `nimib` content to be used in nimibook. 
+- a `docs` folder that contains static assets for the book
+and that will contain the built book
 
-* to build a single page (e.g. `book/mypage.nim`) run first `./nbook dump`
-(which dumps a `book.json` file that contains a table of contents and other context data).
-If `book.json` is present, then you can build your page with: `nim r book/mypage.nim`
-* Each book requires its own ToC and thus will be its own CLI Apps
-* `nbook.nim` is the default name used - it is possible to use another name.
-* Multiple books `nbook.nim` cannot share the same folder. Instead, either split them into two separate books, or merge them into one.
-* Some commands : 
-  * `./nbook clean` will remove generated files and restart from a clean state.
-  * `./nbook update` will update assets and mustache template.
-  * These two commands will modify installed files, use them with caution if you customized files locally.
+**4. nbook build**: run `nim r nbook build` to build the book. Open any `.html` file in `docs` folder to navigate your book.
 
-### Analytics
-
-This website is tracking analytics with [plausible.io](https://plausible.io/index.html), a lightweight and open-source website analytics tool with no cookies and fully compliant with GDPR, CCPA and PECR.
-Analytics for this website are publicly available [here](https://plausible.io/pietroppeter.github.io%2Fnimibook). You can opt out from analytics tracking with [standard ad-blocking](https://plausible.io/docs/excluding) or typing [`localStorage.plausible_ignore=true`](https://plausible.io/docs/excluding-localstorage) in browser console.
-
-<!--refs-->
-[mdbook]: https://rust-lang.github.io/mdBook/index.html
-[Nim]: https://nim-lang.org/
-[nimib]: https://pietroppeter.github.io/nimib/
-[Gitbook]: https://github.com/GitbookIO/gitbook
-[nim-mustache]: https://github.com/soasme/nim-mustache
-[nimibook]: https://pietroppeter.github.io/nimibook/
-[GFM]: https://github.github.com/gfm/
-[nim-markdown]: https://github.com/soasme/nim-markdown
-[cheatsheet]: https://pietroppeter.github.io/nimib/cheatsheet.html
+**5. create your content and enjoy!**: now you are ready to start creating content in your sources and publish your book.
 
 <!--SKIP
 All content before this sign is replicated in the Introduction chapter of nimibook documentation
 -->
 
-## Code structure
+See [nimibook] documentation for more details.
+
+## Contribute
+
+You are more than welcome to contribute!
 
-For an introduction to nimibook's code see [Code Guide](src/readme.md)
+- We usually have some open issues of stuff we need to fix or we would like to do.
+- You have an overview of the code base in [src/readme.md](src/readme.md)
+- The CI is setup to run tests and publish a document PR preview (click on details on the Netlify preview task once it's green), so that we can all check the changes directly from the PR.
+- You should also test and build the book locally, there are nimble tasks to help with that (run `nimble tasks` for the list).
+- If the feature can be tested with a unit test, make sure to add one.
+- Once you make a change, remember to document your changes in the appropriate place in the docs.
+- If you add a module, remember to update the code guide.
+- bump the version (usually a patch increment) so that we can immediately tag and release your contribution.
+- Make sure that the title of your PR is clear and edit the initial message with a few short sentences that will be added to the changelog once we release. 
+
+## Analytics
+
+This website is tracking analytics with [plausible.io](https://plausible.io/index.html), a lightweight and open-source website analytics tool with no cookies and fully compliant with GDPR, CCPA and PECR.
+Analytics for this website are publicly available [here](https://plausible.io/pietroppeter.github.io%2Fnimibook). You can opt out from analytics tracking with [standard ad-blocking](https://plausible.io/docs/excluding) or typing [`localStorage.plausible_ignore=true`](https://plausible.io/docs/excluding-localstorage) in browser console.

book/cli.nim

@@ -0,0 +1,55 @@
+import nimib, nimibook
+import std / strformat
+
+nbInit(theme = useNimibook)
+nbText: fmt"""# Commands
+
+With the `nimibookCli(book)` command at the end of `nbook.nim` file,
+the executable is provided with a number of commands.
+The help on the executable can be obtained running `nbook` without arguments:
+
+```
+{cliHelp}
+```
+
+## Customize nim compile time parameters
+
+During build nimibook compiles and runs a `example.nim` file
+with `nim r <nimOptions> <srcDir>/example.nim`.
+Any additional argument after `build` is used as-is in `<nimOptions>`.
+
+For example to compile the whole book in release mode with no hints
+or other messages from the compiler you can run:
+
+```
+nbook build -d:release --hints:off --verbosity:0
+```
+
+## Single nimib document build
+
+When you are working on a single nimib document you are not interested in
+building the complete book. In order to build a single file
+you need first to dump the `book.json` with `nbook dump`.
+After this is done you can build the single `example.nim` file
+as you would with standard nimib. For example to show it in the browser after
+build is completed you can run:
+
+```
+nim r book/example.nim --nbShow
+```
+
+## Parallel build and error logs
+
+By default nimibook builds source files in parallel.
+If an error is produced when building a source file a `.log` file
+with the output of build command is created next to source file.
+
+If you need to disable the parallel builds you can set
+`-d:nimibParallelBuild=false` when compiling `nbook`.
+
+By default it builds up to a maximum of 10 source files in parallel.
+To change the default maximum to `n` you can set
+`-d:nimibMaxProcesses=n` when compiling `nbook`.
+
+"""
+nbSave