fransbouma/docnet

Your friendly static documentation generator, using markdown files to build the content.

docnet's Issues

Docnet 0.14.0 fails in Win7

The latest version 0.14.0 fails in Windows 7.

Latest version 0.13.x works as expected.

Problem with NavigationLevel.cs

Debug output:
`d:\apps\DOCNET>docnet d:\apps\DOCNET\DOCNET_HELP\DocNet-gh-pages\MarkdownSource
Docnet v0.14.0. (c)2016 Frans Bouma
Get your copy at: https://github.com/FransBouma/Docnet

Copying theme 'L2NoSearch'
Copying source folders to copy.
Generating pages in 'd:\apps\DOCNET\DOCNET_HELP\DocNet-gh-pages'
Exception: System.IO.DirectoryNotFoundException
Description: En del af stien 'd:\apps\DOCNET\DOCNET_HELP\DocNet\src\DocNet\NavigationLevel.cs' blev ikke fundet.
Stack-trace:
ved System.IO.__Error.WinIOError(Int32 errorCode, String maybeFullPath)
ved System.IO.FileStream.Init(String path, FileMode mode, FileAccess access, Int32 rights, Boolean useRights, FileSha
re share, Int32 bufferSize, FileOptions options, SECURITY_ATTRIBUTES secAttrs, String msgPath, Boolean bFromProxy, Boole
an useLongPath, Boolean checkHost)
ved System.IO.FileStream..ctor(String path, FileMode mode, FileAccess access, FileShare share, Int32 bufferSize, File
Options options, String msgPath, Boolean bFromProxy, Boolean useLongPath, Boolean checkHost)
ved System.IO.StreamReader..ctor(String path, Encoding encoding, Boolean detectEncodingFromByteOrderMarks, Int32 buff
erSize, Boolean checkHost)
ved System.IO.File.InternalReadAllText(String path, Encoding encoding, Boolean checkHost)
ved System.IO.File.ReadAllText(String path, Encoding encoding)
ved Projbook.Extension.DefaultSnippetExtractor.LoadFile(String fullFilename)
ved Projbook.Extension.CSharpExtractor.CSharpSnippetExtractor.Extract(String fullFilename, String memberPattern)
ved MarkdownDeep.BlockProcessor.HandleSnippetExtension(Block b)
ved MarkdownDeep.BlockProcessor.HandleDocNetExtension(Block b)
ved MarkdownDeep.BlockProcessor.EvaluateLine(Block b)
ved MarkdownDeep.BlockProcessor.EvaluateLine()
ved MarkdownDeep.BlockProcessor.ScanLines()
ved MarkdownDeep.Markdown.ProcessBlocks(String str)
ved MarkdownDeep.Markdown.Transform(String str, Dictionary2& definitions) ved Docnet.Utils.ConvertMarkdownToHtml(String toConvert, String destinationDocumentPath, String siteRoot, String sour ceDocumentFilename, List1 createdAnchorCollector)
ved Docnet.SimpleNavigationElement.GenerateOutput(Config activeConfig, NavigatedPath activePath)
ved Docnet.NavigationLevel.GenerateOutput(Config activeConfig, NavigatedPath activePath)
ved Docnet.NavigationLevel.GenerateOutput(Config activeConfig, NavigatedPath activePath)
ved Docnet.NavigationLevel.GenerateOutput(Config activeConfig, NavigatedPath activePath)
ved Docnet.Engine.GeneratePages()
ved Docnet.Engine.DoWork()
ved Docnet.Program.Main(String[] args)
Inner exception:

d:\apps\DOCNET>docnet

`

Set index page for automatic page creation ?

Upgraded to v 0.16, really like the automatic page generation feature. Makes it trivial to add lots of auto-generated pages.

But if I generate a page in a non-English language, it's a bit annoying to have the automatic index page forced.

Would it be possible to add option to set an index page name, like "__index.md" or similar ? That way the logic from json file is continued, and it can be used or left out as desired.

I did try something like
"Mylooptest" {
"__index" : "loopdir/**"
}

.. but it created an undesired result.

Alternatively - I could design my own auto-index-page, but I guess that would open a whole can of worms.

Thanks for a great product!

a space in a tab header text isn't supported

See: http://fransbouma.github.io/DocNet/markdownextensions.htm

Specifying

@tab This is a header
content
@end

will make the tab have the header 'This' and the rest of the header 'is a header' is added to the tab content.

Caused by a faulty regexp which filters in \s after the first word, which isn't sufficient. It explicitly has to match a \n at the end of the line.

Move Utils.IncludeProcessor's logic to the span parser

It currently uses a regexp, which is not how markdowndeep works, and it matches @@include directives in code blocks as well. The markdowndeep parser's span parser is a likely candidate to add the @@include directive parser.

Replace Markdown parser with MarkdownDeep

(See #11 why this is needed)

The MarkdownSharp parser is fatally flawed: the html paragraph finder uses a regex that is broken, yet it's very long/complex. This makes it skip html block elements it should hash/escape otherwise and wraps them in paragraph tags, causing flawed HTML output.

MarkdownDeep is another markdown parser and we'll move to that. This has consequences: the extensions used by DocNet have to be ported as well.

Add setting for configuring include folder

It's currently 'Includes' by default, it should be configurable.

Utilize new MarkdownDeep features

This e.g. means setting root paths for image size etc.

Proposal: NuGet package for msbuild integration

I took some time in a fork to create a simple tool NuGet package that integrates the DocNet commands into msbuild. This allows you to easily integrate DocNet into a project's build process. Is there any interest in taking a look at a pull request? I'd be happy to write up some documentation as well.

Where to store the attachments

Just a question someone might have already solved. Where do you store the attachments?

1. In a separate includes/attachments folder (nested or flat)
2. Next to the md src files

Support API reference documentation

I've been looking for the "ultimate" documentation tool and this comes close 👍

One thing I am missing is the option to generate API reference documentation based on the xml docs from the api. Maybe it can be combined with https://github.com/Geaz/sharpDox ?

Then we could integrate with disqus and the docs would be near perfect. If you want I can help out, but need to know whether you would be interested in such a thing.

1. Support disqus at the bottom of the docs
2. Support API reference doc generation

Update documentation with MarkdownDeep support

This means update the doc site, with the new MarkdownDeep support, incl. credits and features it brings to the table.

Generate 404 page

Sometimes you get a 404 page. It would be nice if we could generate a 404 page (including ToC).

Implement Projbook's Snippet include feature

Projbook supports inclusion of snippets from external files. This is particularly helpful if you e.g. want to include a method or class from a C# file into documentation: by using the inclusion of a snippet, the original text is included as a fenced codeblock and it's not a burden to keep things in-sync.

The proposed syntax is:

@snippet language [filename] pattern

As Projbook is MIT licensed, we can include their extractors for C#, XML and plain text, and use that. The C# extractor is particularly helpful as it's based on Roslyn and supports some neat syntax. See: http://defrancea.github.io/Projbook/projbook.html#Pageextractormd-c--pattern

In the syntax above:

• language is either cs, xml or txt. If an unknown string is specified, txt is assumed. The language is used for which extractor is used, and also for the language for the resulting fenced code block.
• filename is a filename to the file to read the snippet from, which is relatively specified to the markdown document the statement is specified in.
• pattern is the pattern to pass to the extractor and this follows the Projbook syntaxis.

Tasks:

• Implement code
• Add @snippet statement to docs
• Add ProjBook theme

Known issue: auto-generated index files for sections can clash on name

See: #61 for a PR that didn't get merged, but has a discussion about the issue.

See #61 (comment) and #61 (comment) about the details regarding this issue.

This issue can only be solved if it allows docnet to generate documentation which matches the output with the bug, as existing documentation relies on this bug and that can't change as that's too much work. I posted this tool on github for others to use as well, but not with the intention to give myself a lot of extra work (as the tool is used by our own documentation, and fixing this issue causes problems with our massive set of docs which rely on this documentation already as well as external links to the docs) due to changes in this application.

I know this issue is likely not affecting a lot of people but nevertheless it can be something you run into.

To really properly solve this, folders where files are generated in shouldn't be in the docnet.json file with the file description, instead the folders should be defined in the section header, so files in a section inherit the folder. Example of how it is now:

"Quick start guides" :
{
	"From Database to source code": 
	{
		"__index": "qsg\\dfscenario1\\index.md",
		"Create a project" : "qsg\\dfscenario1\\CreateProject.md",
		"Create entities based on a database": "qsg\\dfscenario1\\df_reverseengineer.md",
		"Generate source code":"qsg\\dfscenario1\\generatesourcecode.md"
	},

how it should be:

"Quick start guides" :
{
	"__folder": "qsg",
	"From Database to source code": 
	{
		"__folder": "dfscenario1",
		"__index": "index.md",
		"Create a project" : "CreateProject.md",
		"Create entities based on a database": "df_reverseengineer.md",
		"Generate source code":"generatesourcecode.md"
	},

The files then inherit the path from the container(s) they're in and this won't lead to clashes, as everything has a proper folder: auto-generated index files can be placed in the right folder as the containing container section has a folder (or inherits it from its parent, which then will be the same).

Additionally, "__folder" could be optional, in which case the folder is created from the section name.

This is a format change and behavior change and therefore does require a setting, to make it possible to switch between the behavior (so existing behavior is preserved).

Feature request: urls without ".htm"

If I create a "MySection.md" file using docnet, it will be transformed to MySection.htm with url like http://mydomain.com/MySection.htm which looks ugly and old school. I want to form url in the http://mydomain.com/MySection/ format. It should be easy to implement: we just have to generate MySection folder with index.htm file instead of MySection.md file.
Such feature could have an additional parameter in docnet.json wich allows enabling of disabling it.

Support for @@render tag

@FransBouma First of all thanks a lot for creating DocNet. It is one of those things which I always wanted to do but could never get around to doing it. This is massively helpful. I am moving all my documentation from node.js assemble based website to DocNet. While doing so I am facing two limitation:

1. Support for include tag: This was easy and I have submitted a PR to do this.
2. Support for render tag:
   A render tag could be used as below:

@@render(<path to handlebar template>, <path to JSON file containing the data for the template>)

The above will allow users to auto generate portions of the documentation. For me the use case is to document models of REST end point. I have the specification available in Swagger format. I want to embed the models in documentation using the above approach. This can also be used to generate complex structures like tables etc in docs which is not directly possible with markdown.

Initially I wrote a F# script to do so but now I wanted to check with you, if you would be interested in such a feature? If yes then I can send a PR :-).

Implement Special attribute blocks for ExtraMode in markdown

The MarkdownDeep parser doesn't support special attribute blocks as described in PHP Markdown Extra https://michelf.ca/projects/php-markdown/extra/, and they can be handy to e.g. specify a specific class on an image.

The auto-generated topic list on a missing __index contains a typo

If more than 1 topic is in the section, the automatically generated page for the missing __index page says:

Please select one of the topic in this section:

this should be

Please select one of the topics in this section.

If there's no header defined, no sub headers are added as links to the TOC

E.g. if you have

(some image link)

## topic 1

## topic 2

these won't show in the ToC. If a header is added with ======, they are.

Add requirements to readme

The readme lacks requirements to run the app. (.NET 4.6.1 full), and what it can handle (all markdown files).

Suggestions / ideas for DocNet

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 !

Samples directory?

Looking through the code provided, there's no real documentation (HA!) about what the JSON files and directory contents should be / look like. Can you take the source you created http://fransbouma.github.io/DocNet/index.htm from, and put it in a Sample directory?

Header and hr elements are surrounded by HTML paragraph elements in output

The output is not correct, due to a bug in the markdown parser (or misconfiguration).

The snippet:

# This is a header
blablabla

will result in the following HTML:

<p><H1>This is a header></p>
<p>blablabla</p>

This isn't correct, headers shouldn't be inside P blocks. Browsers will move the p block below the header. This causes too much space which is currently compensated in the CSS for header tags (negative margin), but should be corrected in the markdown parser.

Link to an example maybe?

New features

Some good features to add to DocNet.

1: Export to pdf feature
It is very common that one would need to export a version of the documentation automatically to pdf format...
(This would also need to include version nr of the documentation)

(Please note the need to links inside the pdf too, and pictures to be embedded...)

2: Automatically translate
Use one of the online services to automatically translate the content to another language.

The path on the generated __index replacement page isn't relative to the root

This means that an __index replacement page (which is created for a navigation level which doesn't have a __index page defined) for a navigation level that's in a subfolder isn't prefixed with e.g. ../.

font-awesome extension can't deal with multiple '-' in name

E.g. @fa-arrow-right will result in fa-arrow while it should parse to the next whitespace or EOL/EOF

Support heading 3 items in the side-ToC (as option?)

See for example this page:

http://docs.catelproject.com/vnext/reference/Catel.Core/Catel/Argument.htm

Would be extremely useful to have a list of properties / methods on the left side as well. I can create a PR if you are interested.

HTM vs HTML

Is there a configuration option so the generated html files use extension html instead of htm?

Improve logging

While debugging my solution to #48 , I accidentally found out that some images were missing / could not be resolved. I think this can be improved by adding colored logging.

Add CSS / HTML Tab support

Currently there's no easy way to define CSS/HTML tabs. In general these are ul/li trees with some CSS and perhaps some JS attached to them.

We can't use bootstrap as we already use a CSS system, the css/js has to be standalone usable.

The tabs support should come in the form of @directive tags in the markdown extensions, similar to the @Alert elements currently supported.

Typo in filename

Not sure if worth fixing, but wanted to let you know.

Auto-generated index files clash

For API generation, I have multiple assemblies with the same root namespace. This clashes because the index files are created at the root level.

Would you accept a PR that creates the index files in the target directories or can we force the generation of a unique name in a different manner?

For example, in this case:

http://docs.catelproject.com/vnext/Catel.htm

A name like this would solve it:

api-reference-catel-core-catel.htm
api-reference-catel-serialization-json-catel.htm

Implement Super- and Subscript extension

Some markdown flavors have super/subscript extensions:
^superscript^ and ~subscript~

This is not hard to add.

favicon.ico path customization

The default template contains the following line:

<link rel="shortcut icon" href="favicon.ico">

However, if we put a favicon.ico file in the root src folder, it will not be copied to the output folder. We also have the SourceFoldersToCopy parameter in docnet.json. It would be nice to have a way to customize path to favicon.ico and copy the corresponded file by default.

Allow pretty url formatting

For example, I'd rather have "API Reference" being converted to "api-reference" than "APIReference". I can create a PR with a setting with unchanged default behavior:

UrlHandling: Default | SplitByDashes

Support automatic linking

I am currently converting a large documentation site from Confluence to docnet. So far so good, but I noticed (it's also documented) that links to local md files don't get transformed.

Interested in a PR?

If so, links will be converted if:

1. They are listed in docnet.json (so have a generated htm page)
2. Are relative

pre.nocode css rules define margin bottom to 0

This leads to bad looking pages. THe margin to 0 set was necessary for normal code spans, but not for pre blocks without styling

See: http://fransbouma.github.io/DocNet/markdownsupport.htm#highlighting-code where the code block that's not highlighted has no bottom margin

Related to changes made in commit: 868ed6a

Implement way to center text in markdown

Currently the only way (which is lame) to center things is by using the <center> tag directly.

It would be nice if there was a way to specify a center start/end which then would be converted into a <div class="center"></div> section.

Maybe support Redcarpet extensions?

GitHub uses the Redcarpet renderer for .md content...

https://george-hawkins.github.io/basic-gfm-jekyll/redcarpet-extensions.html

?

Thanks, Chad

Nesting groups without index pages could lead to 'Collection was modified' exception.

A set of nested groups will lead to an exception:

Exception: System.InvalidOperationException
Description: Collection was modified; enumeration operation may not execute.
Stack-trace:
   at System.ThrowHelper.ThrowInvalidOperationException(ExceptionResource resource)
   at System.Collections.Generic.List`1.Enumerator.MoveNextRare()
   at System.Collections.Generic.List`1.Enumerator.MoveNext()
   at Docnet.NavigationLevel.GenerateOutput(Config activeConfig, NavigatedPath activePath) in C:\Myprojects\VS.NET Proje
cts\Github\FransBouma\DocNet\src\DocNet\NavigationLevel.cs:line 93
   at Docnet.NavigationLevel.GenerateOutput(Config activeConfig, NavigatedPath activePath) in C:\Myprojects\VS.NET Proje
cts\Github\FransBouma\DocNet\src\DocNet\NavigationLevel.cs:line 95
   at Docnet.NavigationLevel.GenerateOutput(Config activeConfig, NavigatedPath activePath) in C:\Myprojects\VS.NET Proje
cts\Github\FransBouma\DocNet\src\DocNet\NavigationLevel.cs:line 95
   at Docnet.Engine.GeneratePages() in C:\Myprojects\VS.NET Projects\Github\FransBouma\DocNet\src\DocNet\Engine.cs:line
98
   at Docnet.Engine.DoWork() in C:\Myprojects\VS.NET Projects\Github\FransBouma\DocNet\src\DocNet\Engine.cs:line 47
   at Docnet.Program.Main(String[] args) in C:\Myprojects\VS.NET Projects\Github\FransBouma\DocNet\src\DocNet\Program.cs
:line 53
Inner exception:
<null>

because the engine will create an index page for the group, but by doing that is changing the set of elements of the group (to add the index). This doesn't always succeed, as sometimes it can lead to the exception above.

Generate sitemap

To create improved search capabilities, I think it would help to generate a sitemap?

Let me know if you are interested, then I can try to create a PR.

Include permalink links in all headers

Now only H1 and H2 headers are directly reachable through a permalink. We need to have all headers have permalinks so e.g. H4 and H5's are also directly reachable through a permalink. Do this by adding an anchor element with a fontawesome icon inside the header. This is a custom extension of the markdown deep parser. It uses the 'headerlink' css class.

Russian language support

Hi! DocNet is a great tool but I have problems with russian encoding.
When I try to set russian text in footer I get - ?????
And I cant search anything in russian (I use Firefox).

It would be great to have an option to turn on/off search.

Code inside alert elements inherit line height from container DIV

This gives badly formatted code blocks. The fix is:

div.alert > pre > code {
	line-height: initial;
}

being added to theme.css

Home (__index) not auto-generating ToC

It looks like the Home item does not auto-create the ToC based on the headers. Is that by purpose or a bug?

Add more replacement variables for the templates

I am trying to create a footer like this:

<p>Is this section not up-to-date or found an issue? Please <a href="https://github.com/Catel/catel.github.io/src/{{RelativeFileName}}" target="_blank">contribute</a>!</p>

Therefore I think we could introduce a few new variables:

1. FileName (full path to the file being processed)
2. RelativeFileName (relative (to the docnet.json file) file path of the file being processed)

What do you think? Happy to PR.

Default theme: pages refer to search page with different casing in name as generated search page

Generated pages refer to Docnet_Search.htm, page generated is Docnet_search.htm, which gives 404 on case sensitive servers. (like ... this one ;))

Implement custom named Anchor markdown extension

To be able to refer to parts of a document it should be possible to place an anchor at the position to reference so elsewhere a document can link to it.

E.g.
@anchor Foo

will result in
<a name="Foo"></a>

and can be referred to with #Foo

It's not a high priority, the markdown parser does allow <a name="Foo"></a> html but falling back to html is something that should be avoidable.

Default theme: Text inside a tab uses different font / font characteristics

The Font on a tab page uses different CSS, likely it falls back to the default css and forgets the css set for p and the like. The theme therefore has to have updated css to make this look better