Suggestions

[kerrycobb]

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).

[pietroppeter]

Thanks for reaching out, providing suggestions, and offerring help. let me try to address them one by one:

1. Have the option to hide the numbers in the table of contents.

If by that you mean to not having an entry numbered, you can do it with draft (see here. This was actually wrongly named as draft (in the original mdbook it was used for context not yet existing). We should fix the naming (I will open an issue; edit: see #44). If not can you give an example? Only some chapters would have numbers hidden or all of them?

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.

this is not currently doable but it could be done, there is a similar feature in mdbook (called part title see here), which would add a non clickable section element to the top (only top level it seems). We could do something similar or work differently. I will open an issue (edit: #45) to discuss this further and give you pointers to source.

3. Easier custom favicon or better documentation if one exists. I gave up figuring out how to add a custom favicon.

Note: I am noticing only now that favicon might be broken on Mac (I used to develop only on windows). Might this be your case (we should open an issue for it)? otherwise below the explanation.

Documentation is definitely one of the areas of needed improvement, but do not hesitate to reach out for questions about cases like this.

How the favicon can be set is visible in these lines in document mustache template:

{{&favicon_escaped}}
{{#favicon_svg}}
<link rel="icon" href="{{ path_to_root }}assets/favicon.svg">
{{/favicon_svg}}
{{#favicon_png}}
<link rel="shortcut icon" href="{{ path_to_root }}assets/favicon.png">
{{/favicon_png}}

by default nimibook uses the whale emoji favicon as used by Nimib and it sets the default in this line which is then used by the useNimibook theme command (note to self, favicon escaped is present as book configuration but favicon png and favicon sag are not).

For a single document you would override this by adding after nbInit (for example if you want to use a favicon_svg):

nb.context["favicon_escaped"] = ""
nb.context["favicon_svg"] = true 

You will also need to add the a file named favicon.svg in docs/assets

In general this is impractical to do for all documents, so in order to override a default for the whole book you should define a useMyTheme which would normally call useNimibook and then override the defaults like above. Some configuration is available as book attribute and in particular if you want to just change the value of favicon_escaped you can do in your main book file (without the need of a custom useMyTheme).

4. Have more control over the window titles. Especially the index.html files.

You mean the title of the tab (the one that is set in title element in head of html)? this can be changed through nb.context["title"] = "my title" after nbInit. The default is set here.

5. Be able to insert the TOC with links into pages. Like this https://github.com/badboy/mdbook-toc

This is something that should be made available both for Nimib and nimibook and related to the fact of make headers linkable (see issue pietroppeter/nimib#58). As mentioned in that issue, currently cheatsheet example provides a workaround on how to implement an inline toc. The official way will come after I complete my work on pietroppeter/nimib#35 (which I shall soon resume).

6. Translate links to other pages into a valid link in the html output. Be able to do something like [Link](./relative-path).

I think it should already work but we should definitely add examples of that in the documentation. Once you know the folder structure you should be able to link for example to Table of Contents DSL from Entry in nested section using something like [go to toc](../tocdsl.html). It probably should be made more ergonomic, suggestions on how to do that are welcome.

[kerrycobb]

Thanks for clarifying some things for me!

1. I am referring to something like the draft command. I think it would also be desirable to have the option for sections as well. mdBook has a no-section-label option which hides the number for all parts of the TOC. I like the greater level of control you could have using a different command for each entry (draft) or section if that exists or could be made.

2. I am on a mac. But I was also trying to do this differently trying to copy and example I came across in another project. I'll try it again and see if I can make it work.

3. That is what I am referring to. I am glad to learn that it is possible to change manually. I think it would be better if the title defaulted to the label of the section or entry rather than the file name.

I had an additional thought after posting this. Something annoying about looking at code on published notebooks and markdown documents is it is necessary to copy and paste code from different sections before trying to run it. A command like nbsave which would aggregate all of the code into a single file which could be linked to in the tutorial would be really convenient.

[pietroppeter]

created issues for the stuff mentioned above (#44, #45)

it would also be desirable to have the option for sections as well. mdBook has a no-section-label option which hides the number for all parts of the TOC

could be done: #47

I think it would be better if the title defaulted to the label of the section or entry

agree: #46

I had an additional thought after posting this. Something annoying about looking at code on published notebooks and markdown documents is it is necessary to copy and paste code from different sections before trying to run it. A command like nbsave which would aggregate all of the code into a single file which could be linked to in the tutorial would be really convenient.

In nimib we have a show source which shows the source of the notebook (with all nimib commands). in nimibook this is not there, which is kind of a pity. what you ask though, if I understand is different, and it is about collecting all snippets of code and have the possibility to show it to the user for a better copy and paste. Apart the fact that we should have a copy and paste icon on every piece of code (feature for nimib), I think for the moment I would prefer to let the user build its own way of doing this, it should be rather straightforward (at the end of document you collect all code in previous code blocks and then add a new code block with just discard and ovveride its content). It could be a command called nbCollectAllCode. In any case it would belong to nimib repo rather than this repo.