I am trying to build a single-page book.

Error output (truncated log)

nim c -r -d:release nbook.nim build

[...]
[nimib] current directory: /home/kolmogorov/Documents/dev/algoMathBroRemy
[nimib] saving file: book/LogisticSequenceAndChaos.html
entries.nim(14)          check
Error: unhandled exception: Error finding docs/LogisticSequenceAndChaos.html : no such file or directory [IOError]
Error: execution of an external program failed: '/home/kolmogorov/Documents/dev/algoMathBroRemy/nbook build'

My machine

OS: Archlinux

nim -v
Nim Compiler Version 1.7.3 [Linux: amd64]
Compiled at 2022-10-01
Copyright (c) 2006-2022 by Andreas Rumpf

git hash: 96c5586d030a97d9da2f08b2faacad8d34ebd2e4
active boot switches: -d:release

nimble list -i --ver
nimib  [0.3.1, 0.3.2, #head]
nimibook  [0.2.1, #head]

Book index

import nimibook

var book = newBookFromToc("Nim for mathematical problems", "book"):
  # section("Dummy", "index"): 
  entry("Logistic Sequences And Chaos", "LogisticSequenceAndChaos.nim")

# access to nimibook cli which will allow to build the book
nimibookCli(book)

Book page ("LogisticSequenceAndChaos.nim")

import std/[strutils, sequtils, strformat]
import nimib, nimibook
import plotly
import chroma

nbInit(theme = useNimibook)

nbText:"""
# Logistic Sequences and Chaos
"""

nbCode:
  var colors = @[Color(r:0.9, g:0.4, b:0.0, a: 1.0),
                 Color(r:0.9, g:0.4, b:0.2, a: 1.0),
                 Color(r:0.2, g:0.9, b:0.2, a: 1.0),
                 Color(r:0.1, g:0.7, b:0.1, a: 1.0),
                 Color(r:0.0, g:0.5, b:0.1, a: 1.0)]
  var d = Trace[int](mode: PlotMode.LinesMarkers, `type`: PlotType.Scatter)
  var size = @[16.int]
  d.marker =Marker[int](size:size, color: colors)
  d.xs = @[1, 2, 3, 4, 5]
  d.ys = @[1, 2, 1, 9, 5]
  d.text = @["hello", "data-point", "third", "highest", "<b>bold</b>"]

  var layout = Layout(title: "testing", width: 1200, height: 400,
                      xaxis: Axis(title:"my x-axis"),
                      yaxis:Axis(title: "y-axis too"), autosize:false)
  var p = Plot[int](layout:layout, traces: @[d])
  # p.show()

nbSave

Additionnal informations / remarks

This is not very minimal as a MWE (Minimal non Working Example), but I'll reduce the code size when I have more clue why the html has not been generated under the docs folder.

• this library when installed should also build a binary (called either nbook or nimibook)
• the binary provides all the functionalities needed to build your book
• this feature depends on the support of SUMMARY.md, see #62

Seen in this live example: https://philippmdoerner.github.io/Snorlogue/bookCompiled/customDatatypes.html

There is an additional entry (change log) but "next" arrow is not appearing (in changelog the "previous" arrow appears)

Cc @PhilippMDoerner

The following is my design idea for a cli-generating template nimibookCli that will allow to support deploy mechanism (see discussions in #12, #19).

nbook.nim

main file for managing a nimibook project should be a nbook.nim (renamed genbook since it will do more) with the following structure:

import nimibook

var book = newBookFromToc("My book", "book"):
  entry("Introduction", "index")
  # other entries
  
book.git_repository_url = # ...
# other book configurations

nimibookCli # a template provided by nimibook library

Note that the cli should be a real cli and not based on compile time switches as currently is. This means in particular that unless the toc or book configuration change, there is no need to recompile.

The user starting from an empty repository and adding a file with the above content, should be able to call the following commands with the generated cli (after calling nim c nbook or calling directly nim r nbook <command>).

nbook init

On first call it will create the initial folder structure:

.
├── book              # source of the book
│      ├── index.nim  # basic structure for nimibook nim file
│      └── ...        # other nimibook documents and folders needed for the toc
├── docs              # build location for the book
│      └── assets     # css, js, fonts, ...
├── templates         # mustache templates
├── nbook.nim         # source for toc, book configuration and cli
├── .gitignore
├── config.nims
└── README.md

Inside book folder it will create appropriate nim and md files reflecting current toc.
On subsequent call it will not overwrite existing files. So if init is already called once it will likely only add new files if they have been added to the toc. If you provide a folder or file it will restrict the init operation to that specific folder or file.

nbook check

It will check that current folder structure reflects book toc, configuration (and the internal nimibook assets). It will also lists any other files that are not reflected in current structure.
You should be able to provide a path (folder or file) and the check operation should be restricted to that folder or file.

nbook clean

It will remove all files that should not be represented by current structure. It will also remove outputs of build process (e.g. book.json and html files). It should have a mechanism to protect specific files or folders (some api that you put in nimibook? something like book.keep = @["somefolder", "some/file.nim", ...]). You should be able to provide a path (folder or file) and the clean operation should be restricted to that folder (or file).

nbook build

It will build the book output starting from the toc and generating all files. If you provide a folder or a file it will restrict the build operation only to that folder or file.

nbook update

Same as init but it will overwrite the content instead of doing nothing in the case that a file exists.

currently the check command quits on failure. we could refactor it to actually return the number of failures.
It should be the CLI that quits when failing. An advantage would be able to easily create tests that assert on expected number of failures.

• fix this https://pietroppeter.github.io/nimibook/cli.html
• see #64 (comment)

similar to non-section-label in mdbook: https://rust-lang.github.io/mdBook/format/configuration/renderers.html?highlight=no-section-label#configuring-renderers

toc entries should be able to override this behaviour.

• clean should log what is being removed

others stuff that we should log in the cli?

should be rather straightforward to implement:

• looking at document.mustache starting from this line but also in a later section we need to provide (if relevant) a next or previous object with a link field inside the context (or maybe we can simplify and provide next and previous fields directly as link, do not see why the need for a more complex object).
• this next and previous links must be generated in nimibook.docs while processing the toc

currently the title is name of source file as in nimib. here we do have better information (entry title/label), we should use it.

• Content should be displayed in a single page
• ToC should be still be usable for navigation.

For that we need to :

• Combine the <main> section of generated html page into one file
• Adapt the navigation bar.

Or alternatively, this could be a new theme entirely; whichever is easier.

For reference to https://forum.nim-lang.org/t/8249.

As it is now nimiBook will always run the files in -d:release mode (

Proposed solutions:

• Add a buildDebug cmd argument to the CLI. (in addition to init, build, clean etc)
• If the CLI itself is compiled with -d:debug, then the files it compiles should also be compiled with -d:debug.

Any thoughts on this?

in mdbook the draft is a link to a yet-non-existing chapter: https://rust-lang.github.io/mdBook/format/summary.html

in nimibook it is a non-numbered chapter: https://pietroppeter.github.io/nimibook/tocexample/draft.html

we should change the name of draft in toc api and maybe provide a draft entry

How to deploy Nimibook ?

Basically how to deal with 2 scenarios :

• I have existing documentation I want to migrate.
• I want to create a new book from scratch.

Some possible solutions :

• Create a new repo using the template feature of github. This requires creating a new repository "from scratch" and do not work outside of Github.
• Copy & Paste File. This means future evolution of the docs folders (js, fonts, FontAwesome, css) and the mustache files will have to be updated manually.
• Have a proc generateEmptyBook that copy latest docs folder and mustache files from latest Nimibook version. This requires to deploy docs and book with Nimble meaning we'll probably need to flatten the repository (or Nimble will complain) and the proc itself will probably differ between OS's (so added maintenance complexity ?).

So far, I don't see an "ideal" solution.

What do you think ?

I am currently working on fulfilling the legal prerequisites for merging can-lehmann/owlkettle#34. As discussed before on Discord, I would like to compile a list of licenses for the assets redistributed as part of the resulting website. So far I primarily looked at the files in the assets folder. The following is the section I plan to include in owlkettles docs.

We use nimibook to build this documentation. Nimibook is licensed under the MIT license.

When building a website using nimibook, various assets (code, fonts, styles) are redistributed as part of the website. Here are the licenses for the assets distributed as part of this website. Click on one of the assets to view its license. Note that these licenses only apply to the indicated assets redistributed as part of this website, not to owlkettle or its documentation text.

• Fonts
  • Open Sans (Apache License 2.0)
  • Source Code Pro (SIL Open Font License, Version 1.1)
  • FontAwesome
    • Fonts (SIL OFL 1.1)
    • CSS (MIT)
• Code
  • clipboard.js (MIT)
  • Highlight.js (BSD-3-Clause)
  • book.js (MPL-2.0)
• Themes (MPL-2.0)

It would be great if you could double check that I didn't miss anything.

I also have a specific question regarding the licensing of book.js. I assumed that is licensed under MPL-2.0, since it seems to come from mdBook, which itself is MPL-2.0. Is that correct?

The assumption is based on Section 3.1 of the MPL which states that:

All distribution of Covered Software in Source Code Form, including any Modifications that You create or to which You contribute, must be under the terms of this License.

Note that I am not a lawyer, my understanding of software licenses is quite limited, so take all of this with a grain of salt 😃

this line does something that is not expected: https://github.com/pietroppeter/nimibook/blob/main/src/nimibook/resources/templates/document.mustache#L189

in recent PR #56 clean command has been reduced to only clean the output folder.
it could still use some improvements:

• add a dry-run option
• how to cleanup automatically logs?
• support the keep parameter taking values from nimibook config (so that we can avoid cleaning specific files in output folder
• should we reintroduce an option to perform again cleaning of source folder? (we would need keep to support source folder also)

as done in nimib see pietroppeter/nimib#92 and follow ups

I have multiple files named index.nim in my nimiBook in nimiSlides. And I have gotten two errors in the C-compiler/linker regarding this: link to job And I suspect that it might be due to them using the same filenames in nimcache. This is problematic as you typically have multiple index.nim files in a book (one for each section).

A possible solution to this would be to only allow a single file of each filename to be built at the same time. So if a index.nim file is already being built, and another index.nim file is about to be built as well, it will be put aside until the other file has finished.

I think this could be done using a global HashSet[string] and adding a condition here that checks if the current filename is already in the set or not.

I've used nimibook for a project recently (frogcap.com) and I liked it quite a bit.

I had a few ideas that I think could be valuable additions. I'd be happy to try and work on some of these at some point if any of these ideas would be accepted.

1. Have the option to hide the numbers in the table of contents.
2. Have the option to not generate a page for a given section heading or maybe even do this by default if some content or argument is missing.
3. Easier custom favicon or better documentation if one exists. I gave up figuring out how to add a custom favicon.
4. Have more control over the window titles. Especially the index.html files.
5. Be able to insert the TOC with links into pages. Like this https://github.com/badboy/mdbook-toc
6. Translate links to other pages into a valid link in the html output. Be able to do something like [Link](./relative-path).

This came to me while writing on the owlkettle nimibook.

Owlkettle has a bunch of example.nim files for example applications for individual widgets.
I would love to be able to embed those inside of the owlkettle nimibook instead of linking to the files.

The idea would be something like:

import nimib, nimibook

nbInit(theme = useNimibook)

nbText: """
## Example
Look at this very cool example of a scale widget
"""

nbCode(file = "owlkettle/examples/widget/scale.nim")

nbText: """
As you can see it does wonderful things etc. etc.
"""
...

This is just an example to demonstrate what I mean, what the Syntax for it looks like exactly isn't all that important.

document recent changes done in #50:

• add latex support with latex as in nimib
• document changes
  • refactoring and code structure (review)
  • templates
  • book.json
  • new nb/doc object in Book
  • blocks context in document.mustache
  • refactored Book.book_title into Book.title. Overrides previously existing Book.title which was supposed to be used for the Chapter title
  • cfg stuff
  • note that changes also fix #48 (you should be able to change name of book folder)
  • removed book.path_to_root (it is a document/chapter thing)
  • remove rootfolder in toc and path field in Toc
  • improved init
  • remove default parameters and allow to pass parameters to build
• after nimib 0.3 is released, change nimib dep and release this as 0.3

other improvements (next version):

• add nim code highlighting when starting from md file?
• improve clean? (maybe open an issue)
  • add a dry-run option
  • add keepSrc, keepOut, keepSrcDefaults, keepOutDefaults
• support part title in toc
• support SUMMARY.md
  • a default summary.md should be initialized
• provide nbook binary!
• dumped book.json (now a public api) should not contain cfgDir and it should only contain relative dirs
• quit failures for check and build should be only in cli? (useful for test?)

notes:

• cfgDir should be set as currentDir of nbook
• do I need also a srcDirRel and homeDirRel?
• I am removing srcDir from all entry paths
• srcDir and homeDir always assumed to be relative to cfgDir and always used as string. (maybe nimib should be like that)
• srcDir and homeDir should really be relative strings...
• decided indeed that srcDir and homeDir kept as string relative to cfgDir
• starting to call use outDir instead of homeDir more and more often... (should I change in nimib?)

example https://pietroppeter.github.io/nimibook/tocexample/back_to_parent.html -> https://pietroppeter.github.io/nimibook/.html

not sure why but nimble file is not updated correctly in CI.
to be sure I added a cat nimibook.nimble in CI and the nimble file it is different from the one in main branch.
this leads to a failure since the new jsony dependence is not installed.

• not a feature that is present in original mdbook but it is something which makes a lot of sense: the idea is to have a way to directly show the source code of the page as we do in nimib
• since this is not native in mdbook what needs to be decided is how this elements should appear in the interface: a button? where?

• need to recover a nim highlight js file (see this PR which removed it from nimib some time ago https://github.com/pietroppeter/nimib/pull/15/files#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5)
• add it to assets
• add it as a script in head: pietroppeter/nimib#68
• initialize the script in body

see also pietroppeter/nimib#68 (where there is the discussion for other languages than nim, which also should be in scope here)
the feature should likely be implemented first in nimib and then used here.

Conversation in discord app dev about a potential use of nimibook with owlkettle made me realize that:

• in the toc chapter of docs I am not specifying that section command uses the section folder path implicitly in all entries inside the section!
• also I should make very explicit that the logic is: relative path wrt to srcDir as source is translated to relative path wrt to homeDir (put this in configuration chapter, under folder structure)
  • there is also typo "wit GitHub pages"
  • warn about .. source paths
  • warn about relative assets path (owlkettle use case)
  • I mention also outDir instead of homeDir. Fix that too!

https://github.com/pietroppeter/nimibook/runs/2617698351

it says Only one .nimble file should be present in /home/runner/work/nimibook/nimibook.

Is there some caching mechanism happening there and it still has nimiBook.nimble?

I will try to run it again

Book.json I think should be moved as an output to docs and I think it should be kept as a build output (not cleaned at the end of build, committed in gh-pages). It can be thought as a static api for the whole book. Thoughts?

now that book.json is in docs (so it is published with the book and represents a static api) we should make sure that no absolute dirs are present inside. They should all be relative to cfgDir

right now the content of book is a minimal structure barely related to scinim/getting-started.
the book should instead document nimibook itself.

we should allow the possibility of having a section without path and this would be a section that does not link to any page.
similar to a part title in mdbook (but we should allow it at any indentation level)

The Feature Suggestion

Allow the entries in the sidebar to be "folded in" and "out".

Motivation for this feature

Take this sidebar:

This is likely to grow in the future, making visibility of points below "internals" (and future longer sections) difficult.

It would be nice if I could "fold in" entries of the sidebar so that it can look more like this:

I would suggest this provide the following features:

1. Expand/Collapse on click icon - button

Every section is not just a hyperlink. To the left or right of the section entry in the sidebar should be an icon-button that a user could click on to expand/collapse a section of entries. For a consistent design language, the icons used should likely be chevron icons to indicate that it is currently collapsed (chevron-up) or expanded (chevron down).

The button should highlight on hover separate from the section-hyperlink.

2. Automatically expand section when user is in an entry of that section

In this example: If I am on the page "Build Hook", I would expect the section "Internals" and "Hooks" to be expanded, but not "Adders"

3. Side-consideration: Remove sections having their own pages and make their sole purpose to expand/collapse sections

It may be worth considering maybe making sections no longer their own page but only buttons to expand/collapse sections of a sidebar. That would be a breaking change.

Alternatively, it could be considered to keep section as is and introduce a new grouping mechanism going by the name of group, that you just pass the name it should have on the sidebar and whether the group should be expanded/collapsed initially.

we should map all features that are present in mdbook and not here in appropriate issues.

besides looking at mdbook documentation, an useful list to start with is contained in the html comment hidden in README.md (written while converting index.hbs to mustache).

• we plan to release a nimib based SSG by first half of 2023
• once that is done we should refactor nimibook to use it

a normal markdown file (with no need to run nim code) could generate an html directly.

The change should be in nimibook.publish and we could thus support the following

let toc = newToc("Example", "book"):
  entry("Introduction (only markdown)", "index.md")  # this will create a page starting from the plan markdown
  entry("Another chapter (with nim code)", "chapter.nim")

I guess it makes sense to wait a moment for other small bugs/changes before tagging the 0.1.

When trying to get individual pages of a NimiBook to run in preview mode in NimiBoost I stumbled upon this problem: here in useNimibook it loads book.json which doesn't unless run using the publishing mechanics of NimiBook's CLI. It is on top of that removed after generating the book so reusing it after a first run isn't possible either:

The idea of the preview mode is to focus on the content more than the layout so it doesn't really need any NimiBook functionality to run at all. It can just show every page as the default Nimib theme. So for me yet another commandline switch to disable all NimiBook functionality would work for me (I think). It's just a matter of inserting a when not defined(skipNimibook) in nbUseNimibook.

What do you think? Is there another way to do it?

Not sure why, but we lost the GitHub repo icon. At a first look code looks fine: repo url is set in nbook, should be dumped in book.json, should be loaded in useNimibook and put in the context.

• feature present in mdbook: https://rust-lang.github.io/mdBook/guide/creating.html#summarymd
• SUMMARY.md gives a way for the user to specify the table of content using a plain markdown file
• in this way there is no more need to specify a table of contents in a nim source file and we could directly provide a nimibook executable

I think we should go in this direction and we are actually pretty close.

After looking at the nimibook documentation I would expect this to work:

I have a project directory that looks like this:

├── book
│   └── index.md
├── nbook
└── nbook.nim

The nbook.nim file looks like this:

import nimibook

var book = newBookFromToc("nimibook", "book"):
  entry("Introduction", "index.md")

nimibookCli(book)

When I try to build this, I get this error: Error: unhandled exception: cannot open: book/page.md [IOError]

This seems like it might be a bug or like it would be helpful to explain in the documentation.

I will close this when it is done

• currently in order to add latex functionalities to a document you need to add nb.useLatex to each document
• we could add a useLatex configuration option in the book that activates this for the whole book

should be a rather easy implementation, in particular:

• add a new field (with documentation comment) in BookConfig type (in types.nim)
• a corresponding line should be added in useNimibook proc (in themes.nim)
• document change in book/content.nim (and should be auto documented in configuration)

instead of copying them in book folder while building docs, templates should be used as in-memory partials. if one wants to use a custom head.mustache, then he should commit in book folder (or maybe better we should make docs folder the one where nimib goes looking for templates) and this would provide the ovveride.

Can you change the value "book" in the newBookFromToc() call? I run into errors when changing it to anything else. If it is designed to be changed, then some sort of error is occurring here.

currently gh-pages rebases itself on main: https://github.com/pietroppeter/nimibook/blob/main/.github/workflows/docs.yml#L23

this is bad since if some file was commited at some point in main and later removed it will still be in gh-pages. instead the CI should force gh-pages to be exactly like main (not sure what git command to call there) and than add a single commit on top of that just to commit the html and new stuff being produced.

see also #30

if there is an error during async build (see #53), having an option todo the standard build might be useful. prompted by SciNim/getting-started#49

this is a small thing but it kind of bothers me. the name was nimiBook as a calque of mdBook, but then I do not like that I have nimiBook.nimble files, hence the renaming. I guess this might be a bit bothering since we will have to change the remoteUrl of git repo (not sure what happens to the forks), so I figure I ask before proceeding. Thoughts @Clonkk, @HugoGranstrom?

Given this nbook:

import nimibook

var book = initBookWithToc:
  entry("Should Be 1.", "book/bla.nim")
  section("Should be 2", "book/internals.nim"):    
    section("Should be 2.1", "internals/adders.nim"):
      entry("Should be 2.1.1", "adders/one_adder.nim")

  entry("Should be 3.", "CONTRIBUTING.md")
nimibookCli(book)

Running these commands:

nimble install -y nimib@#head nimibook@#head
nim c -d:release --mm:refc nbook.nim
./nbook init
./nbook build

Generates this Sidebar:

The numbering is correct, but the indentation isn't.
The indentation implies that "Should be 3" is a sub-entry of the section "Should be 3" instead of a sibling entry.

I assume the logic that generates HTML only goes back one indentation level instead of determining the correct indentation level.

a path option to cli would allow to restrict command such as build or clean to a specific folder.
we could actually go further and be able to support wildcard (only book/myfolder/files_that_start_like_these*).

for discussion generating this see #20