add custom srcdir and update build docs

[pietroppeter]

• with current setup the images are already create in docs/images, but the html file is not
• add a nbPostInit custom include (requires a nimib more recent than 0.1, taken current head but fixed commit) that adds a nbSrcDir (books dir). It also renames nbDoc.filename to the relative position with respect to srcDir. In this way also html file is written in docs folder
• added a .gitgnore that will ignore everything in docs by default. modified the build script so that this gitignore is removed when building docs. also removed rsync since it is not needed anymore (everything is written in docs folder already)

I think I might add a srcDir mechanism like the above in future versions of nimib to support this workflow out of the box but probably the default srcDir will be named "src".

[HugoGranstrom]

Many thanks for helping out! 😄 The only problem I seem to have is that Nimble isn't cooperating really. It complains about nimib@#486c22d9cd9c40f32f00efe9fd46630b9bd4d3c7, but when I changed it to nimib#486c22d9cd9c40f32f00efe9fd46630b9bd4d3c7 it works.

[pietroppeter]

always forget that syntax... and I actually looked it up 🤷‍♂️! https://github.com/nim-lang/nimble#nimble-install

[HugoGranstrom]

Haha same, I only ever use package@#head so it seems natural to just replace head 🙃

I tried fixing the path at the top of the page by inserting this code into nbPostInit:

nbDoc.context["here_path"] = (nbThisFile.relativeTo nbSrcDir).string

But it doesn't seem to have any effect. I was looking at this piece of code where title is set to context["here_path"]. Any ideas why it doesn't work? 😅

[HugoGranstrom]

Oh I see why now: https://github.com/pietroppeter/nimib/blob/4926b61190416ab7b52a42cb5644fffd3163b44d/src/nimib.nim#L51-L54
Defaults is initialized before nbPostInit is run.

[pietroppeter]

yes, you are right. You should also add a doc.context["title"] = nbDoc.context["here_path"] to ovveride the default (or directly override the title). Probably the template itself can be improved (to use here_path if a title is not found). In fact also the home link is wrong and it should change to nbDoc.context["home_path"] = (nbHomeDir.relativeTo nbThisDir).string (and this does not require to ovveride other stuff). Will add a commit with this stuff.

[pietroppeter]

had to add also a nbDoc.partials["header_center"] = "<code>" & nbDoc.context["title"].castStr & "</code>" which clearly shows that templates are not being used correctly there, will have to fix that!

[HugoGranstrom]

Awesome! I feel ready to merge this now unless you have anything more to add 😄

had to add also a nbDoc.partials["header_center"] = "" & nbDoc.context["title"].castStr & "" which clearly shows that templates are not being used correctly there, will have to fix that!

I'm still trying to wrap my head around how Nimib works internally, so correct me if I'm wrong, do I understand it correctly that nbDoc.partials["header_center"] should be a mustache template instead of this manual construction. That way nbDoc.context["title"] won't be used for rendering until at the very end and hence our changes to it in nbPostInit would be visible?

[pietroppeter]

nothing more to add!

yes, you are right, nbDoc.partials["header_center"] should be a template accessing the here_path (more than accessing directly title, which is also used in the head section).
the idea in nimib is that rendering is done only at the end during the save phase and everything can be customized between the nbInit and nbSave. Also, some part of the customization can be done directly through template files without changing the nim file (for example you can add a header_center.mustache file to override the template for all documents.

[pietroppeter]

mmh, the CI for building docs it seems it ran fine but I do not see the changes reflected in the final result...

[HugoGranstrom]

Hmm yeah me neither... I checked the logs and saw this:

Installing nimib@any version
Downloading pietroppeter/nimib using git
  Verifying dependencies for nimib@0.1

So it seems it ignores the hash for some reason :/

Okay nice, good to know 👍
That idea really makes for a fully customizable experience and it reminds me of Nim's philosophy that one isn't dependent on the compiler (or Nimib in this case) to have all the bells and whistles you need because there is nothing stopping you from doing whatever you want. 😄 Oh that's cool, I assume it's good if you want to share it across multiple files?

[pietroppeter]

Hmm yeah me neither... I checked the logs and saw this:

Installing nimib@any version
Downloading pietroppeter/nimib using git
  Verifying dependencies for nimib@0.1

So it seems it ignores the hash for some reason :/

Ok, I will release a new nimib and send a follow up PR.

Okay nice, good to know 👍
That idea really makes for a fully customizable experience and it reminds me of Nim's philosophy that one isn't dependent on the compiler (or Nimib in this case) to have all the bells and whistles you need because there is nothing stopping you from doing whatever you want.

yes, nimib tries to follow nim philosophy as far as I am able to understand it :). The realization that I should just go the nim way ("this is the way") is what actually made me come up with a library and an api instead of a binary file (which will probably eventually come to ease up configuration and scaffolding).

😄 Oh that's cool, I assume it's good if you want to share it across multiple files?

Yes, it could be used to replace the header with some simple navigation common to all pages for example.

[HugoGranstrom]

I restarted the Action and now it installed the correct version... No idea what happendde

[HugoGranstrom]

Ok, I will release a new nimib and send a follow up PR.

Greatly appreciated 🙏

yes, nimib tries to follow nim philosophy as far as I am able to understand it :). The realization that I should just go the nim way ("this is the way") is what actually made me come up with a library and an api instead of a binary file (which will probably eventually come to ease up configuration and scaffolding).

Sounds like a really good realization :) And yes some kind of binary that could replace our nimble genbook for example or more generally a mdBook is a nice feature to have in the future.

Yes, it could be used to replace the header with some simple navigation common to all pages for example.

That's neat!