fransbouma / docnet Goto Github PK
View Code? Open in Web Editor NEWYour friendly static documentation generator, using markdown files to build the content.
Home Page: http://fransbouma.github.io/DocNet/
Your friendly static documentation generator, using markdown files to build the content.
Home Page: http://fransbouma.github.io/DocNet/
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!
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.
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.
Just a question someone might have already solved. Where do you store the attachments?
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
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. ../
.
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:
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.Tasks:
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.
@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:
@@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 :-).
GitHub uses the Redcarpet renderer for .md content...
https://george-hawkins.github.io/basic-gfm-jekyll/redcarpet-extensions.html
?
Thanks, Chad
Sometimes you get a 404 page. It would be nice if we could generate a 404 page (including ToC).
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.
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.
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.
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.
(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.
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.
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.
It looks like the Home item does not auto-create the ToC based on the headers. Is that by purpose or a bug?
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:
What do you think? Happy to PR.
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.
It's currently 'Includes' by default, it should be configurable.
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
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.
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.
This e.g. means setting root paths for image size etc.
E.g. @fa-arrow-right
will result in fa-arrow
while it should parse to the next whitespace or EOL/EOF
Generated pages refer to Docnet_Search.htm, page generated is Docnet_search.htm, which gives 404 on case sensitive servers. (like ... this one ;))
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:
This means update the doc site, with the new MarkdownDeep support, incl. credits and features it brings to the table.
The readme lacks requirements to run the app. (.NET 4.6.1 full), and what it can handle (all markdown files).
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?
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, List
1 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
`
Is there a configuration option so the generated html files use extension html instead of htm?
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.
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.
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
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.
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.
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.
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 !
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.
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.
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.
Some markdown flavors have super/subscript extensions:
^superscript^
and ~subscript~
This is not hard to add.
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).
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
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.
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.
This gives badly formatted code blocks. The fix is:
div.alert > pre > code {
line-height: initial;
}
being added to theme.css
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.