search

FransBouma / DocNet

Your friendly static documentation generator, using markdown files to build the content.
http://fransbouma.github.io/DocNet/
248 stars 36 forks source link

Suggestions / ideas for DocNet #43

Open myicq opened 7 years ago

myicq commented 7 years ago

Thank you to Frans for pointing to missing snippet. DocNet is working great.

Have used it a bit, and have a few suggestions. Feel free to use or not.

1) auto-generate structure It seems backwards to me that I have to edit a JSON file with structure to generate the files. it should be simple, at least by option, to have a JSON file with "global" parameters such as default template and then automatically generate the layout from the directory structure of the source files. Navigation title either from H1 level in source, or from a head matter. By option, user could choose either method.

2) variable structure Sometimes I could use just-in-time variables that could be used inside the templates. It would be possible in the JSON file to have a variable array that could be used inside templates: "Variables" : { "Testvar1" : "This is my testvar1", "testvar2" : "Another variable", "XYZ" : "123" } , and then to use that simply by referencing {{Testvar1}} in template. not present => rendered empty.

3) all options by command line Combine above / some of above, so that options can be specified by command line.

Docnet -name "This is my name" -dest "..\" etc etc

or at least specify JSON file to use by command line. Docnet -j source\thisConfig.json

Thanks for great software !

FransBouma commented 7 years ago

Ad 1: it's a good suggestion, though it might be harder to pull this off than it seems. Every documentation set I've made with DocNet it was necessary to define the nodes in the tree differently than how the files were stored, how the title was in the page etc. The design was primarily that you could define the tree in one place and not scattered around the files / filesystem, as that's rather rigid: the filesystem as structure is easy enough, but titles for treenodes is harder, not to mention the pages per sub node header. It can be an option though to get things started and later on move to a config file if needed.

ad 2: specifying the variables with a page entry in the json file you mean? Remember, there's 1 template file, the markdown files are input :) So variables to configure the only template page, that could work, but then again, you could also add the markdown to make it look like you want to. I haven't had the necessity for these variables, hence I've not built them in. So it requires a use case with a clear example why these are needed.

ad 3: what would that solve if you use a json file? All options are in the json file, so specifying them on a command line seems odd, unless you want to configure the json file for a specific case and not alter the json file, but what specific use case would require that?

btw you could have done Docnet source\. and it would have worked, it will look in the folder you've specified if it can load a docnet.json file. If it finds one, it will load it and use it. :)

GeertvanHorrik commented 7 years ago

  1. will be available (already implemented) soon

  2. might be interesting, what sort of variables are you thinking of @myicq ?

  3. specifying the json.config is already possible? I use this script:

tools\docnet\docnet.exe src/vnext

Or do you want to use multiple different config files in the same directory?