From 56618b5f6c8b3b13e0ebe53b984d5796ea9e4da1 Mon Sep 17 00:00:00 2001 From: Frans Bouma Date: Thu, 4 Aug 2016 11:30:05 +0200 Subject: [PATCH] rebuild of docs with v0.13 --- Authoringcontent.htm | 2 +- Configuration.htm | 2 +- WritingcontentusingMarkdown.htm | 2 +- acknowledgements.htm | 2 +- css/theme.css | 32 ++++++++++++++++++++++++++++++++ docnetjson.htm | 4 ++-- h2leveldiscovery.htm | 2 +- index.htm | 4 ++-- license.htm | 2 +- markdownextensions.htm | 10 +++++----- markdownsupport.htm | 22 +++++++++++----------- search.htm | 2 +- themes.htm | 8 ++++---- usage.htm | 4 ++-- 14 files changed, 65 insertions(+), 33 deletions(-) diff --git a/Authoringcontent.htm b/Authoringcontent.htm index 07fe728..a412095 100644 --- a/Authoringcontent.htm +++ b/Authoringcontent.htm @@ -78,7 +78,7 @@
-

Authoring content

+

Authoring content

Please select one of the topics in this section:

  • Themes
    • diff --git a/Configuration.htm b/Configuration.htm index 298f49a..664f193 100644 --- a/Configuration.htm +++ b/Configuration.htm @@ -77,7 +77,7 @@
-

Configuration

+

Configuration

Please select one of the topics in this section:

  • Site configuration with the docnet.json file
    • diff --git a/WritingcontentusingMarkdown.htm b/WritingcontentusingMarkdown.htm index 58930ba..8e0a431 100644 --- a/WritingcontentusingMarkdown.htm +++ b/WritingcontentusingMarkdown.htm @@ -85,7 +85,7 @@
-

Writing content using Markdown

+

Writing content using Markdown

Please select one of the topics in this section:

  • Markdown support
    • diff --git a/acknowledgements.htm b/acknowledgements.htm index 64fd260..5f1ae33 100644 --- a/acknowledgements.htm +++ b/acknowledgements.htm @@ -70,7 +70,7 @@
-

Acknowledgements

+

Acknowledgements

This application wouldn't be possible without the work of others. The (likely incomplete) list below contains the work Docnet is based on / builds upon.

  • MkDocs. Docnet borrows a great deal from MkDocs: the theme css Docnet uses is based on a cleaned up version of their Readthedocs theme, as well as the javascript based search is from MkDocs.
    • diff --git a/css/theme.css b/css/theme.css index 07f5e01..00d59a1 100644 --- a/css/theme.css +++ b/css/theme.css @@ -136,6 +136,14 @@ a:hover, a:active { outline: 0; } +a.headerlink { + display: inline; + text-decoration: none; + visibility: hidden; + font-size: smaller; + margin-left: 3px; +} + abbr[title] { border-bottom: 1px dotted; } @@ -303,6 +311,30 @@ h6 { margin-bottom: 7px; } +h1:hover a.headerlink { + visibility: visible; +} + +h2:hover a.headerlink { + visibility: visible; +} + +h3:hover a.headerlink { + visibility: visible; +} + +h4:hover a.headerlink { + visibility: visible; +} + +h5:hover a.headerlink { + visibility: visible; +} + +h6:hover a.headerlink { + visibility: visible; +} + hr { display: block; height: 1px; diff --git a/docnetjson.htm b/docnetjson.htm index a1dc029..ffded52 100644 --- a/docnetjson.htm +++ b/docnetjson.htm @@ -79,7 +79,7 @@
-

The configuration file: 'docnet.json'

+

The configuration file: 'docnet.json'

DocNet uses a json file to determine what to do in what form. The format is straight forward and described below

{
     "Name" : "name of site",
@@ -117,7 +117,7 @@
 
 
Paths are expected to use \ characters, and as it's json, you have to escape them, so the path .\foo becomes .\\foo.

 
Each level, starting with the root, has a special page defined, __index. This page is the page shown when the level header (in the example above this is e.g. Sub Header 1) is clicked in the navigation. If __index is specified in the root level, it's assigned to the navigation name Home. If there's no __index specified, there will still be a page generated but it will have default content (See below). The names of the elements are case sensitive.

-
Levels without __index defined

+
Levels without __index defined

 
If a level has no __index defined, DocNet will create a __index entry for the level and will specify as target <path to index of parent>/nameoflevel.md. If the page exists it will be loaded as the content for the index of the level, if it doesn't exist, the HTML will simply contain the topictitle and a list of all the sub topics in the level. This guarantees the tree can always be navigated in full.
diff --git a/h2leveldiscovery.htm b/h2leveldiscovery.htm index 5a72e7e..9fdac4b 100644 --- a/h2leveldiscovery.htm +++ b/h2leveldiscovery.htm @@ -77,7 +77,7 @@
-

Automatic H2 level ToC entry discovery

+

Automatic H2 level ToC entry discovery

Docnet will automatically add all H2 (## marked) headers to the ToC as sub navigation elements below a page ToC item. It will automatically add anchors to these H2 headers in the HTML output for the page as well. This makes it very easy to create a fine-grained ToC for easy discovery.

diff --git a/index.htm b/index.htm index 38ee4ab..f043819 100644 --- a/index.htm +++ b/index.htm @@ -70,10 +70,10 @@
-

DocNet

+

DocNet

DocNet is a static site generator, mainly meant for user documentation, using markdown files to build the content. This site is generated with DocNet and is meant both as a showcase what you can do with the application and also contains the documentation for DocNet.

To see the markdown source of this site, look at the MarkdownSource folder in the gh-pages branch in the DocNet repository at GitHub

-

Get DocNet

+

Get DocNet

To get DocNet, either build it from source using the github repository, or download a pre-build binary package from the 'Releases' section of the github repository

diff --git a/license.htm b/license.htm index 81151b9..4b8c515 100644 --- a/license.htm +++ b/license.htm @@ -70,7 +70,7 @@
-

License

+

License

DocNet is licensed under the following license:

The MIT License (MIT)

Copyright (c) 2016 Frans Bouma

diff --git a/markdownextensions.htm b/markdownextensions.htm index 74b5840..0f5dbff 100644 --- a/markdownextensions.htm +++ b/markdownextensions.htm @@ -90,9 +90,9 @@
-

DocNet Markdown extensions

+

DocNet Markdown extensions

Docnet defines the following markdown extensions to make writing documentation easier.

-

Alert boxes

+

Alert boxes

To quickly define alert boxes, Docnet defines the @alert element. Three types of alerts are defined: danger (displayed in red), warning or important (displayed in yellow) and info or neutral, which is displayed in blue. You specify the type of the alert after the @alert statement using @alert name. Close the @alert with @end.

Below are examples for each alert box and the markdown used to create them.

The markdown:

@@ -125,10 +125,10 @@ This is a tip! It will be displayed in a tip alert box! @end

Results in

Tip

This is a tip! It will be displayed in a tip alert box!

-

Font Awesome icons

+

Font Awesome icons

To specify a font-awesome icon, use @fa-iconname, where iconname is the name of the font-awesome icon.

Example: To specify the font awesome icon for GitHub, use @fa-github, which will result in:

-

Tabs

+

Tabs

It's very easy with Docnet to add a tab control with one or more tabs to the HTML with a simple set of markdown statements. The tab statements are converted into pure CSS3/HTML tabs, based on the work of Joseph Fusco.

To start a Tab control, start with @tabs and end the tabs definition with @endtabs. Between those two statements, which each need to be suffixed with a newline, you define one or more tabs using @tab followed by the label text for that tab, followed by a newline. End your tab contents with @end.

The following example shows two tabs, one with label 'First Tab' and one with 'Second Tab':

@@ -146,7 +146,7 @@ Now, the second tab however is very interesting. At least let's pretend it is!

This is the text for the first tab. It's nothing special

As you can see, it can deal with newlines as well.

Now, the second tab however is very interesting. At least let's pretend it is!

-

Include files

+

Include files

You can include other files in your markdown files using the directive @@include("filename"), where filename is the name of the file to include. The include system isn't recursive. The files to include are read from a special folder, specified under IncludeSource in the docnet.json file. If no IncludeSource directive is specified in the docnet.json file, the folder Includes is assumed.

diff --git a/markdownsupport.htm b/markdownsupport.htm index ad115fd..3dd38d9 100644 --- a/markdownsupport.htm +++ b/markdownsupport.htm @@ -90,17 +90,17 @@
-

Markdown support

+

Markdown support

DocNet uses markdown files as input. The markdown is parsed with the markdown parser from topten software (called 'MarkdownDeep'). It supports the default markdown statements as well as github style code block markers and specific extensions for writing documentation, which are described below.

-

Standard Markdown

+

Standard Markdown

The standard markdown syntax as defined by John Gruber is supported in full.

-

Php Markdown Extra

+

Php Markdown Extra

MarkdownDeep supports PHP Markdown Extra. PHP Markdown Extra comes with a set of neat extensions for markdown to define e.g. tables, footnotes and more. Please see the link above for all the syntax examples. Additionally, you can look at the unit test files for MarkdownDeep in the DocNet respository at GitHub.

A couple of examples are given below

-

Footnotes

+

Footnotes

MarkdownDeep supports Footnotes, which can be added through the following system: To specify a footnote marker, specify [^1], which will result in:1

The actual footnote text is then specified with [^1]: following the text of the actual footnote. Click on the superscript 1 link above to go to the footnote rendered at the bottom of this page.

-

Definition lists

+

Definition lists

To specify simple definition lists, simply do:

Item one
 :   this is the description of item one
@@ -114,7 +114,7 @@ Item Two
 
Item Two

 
this is the text of item 2

 
-
Tables

+
Tables

 
There's basic support for defining tables. 

 
Specifying: 

 
Fruit|Color
@@ -150,14 +150,14 @@ Bongo|Bongo... it's a strange color, do you have a minute? It's a bit like the s
 
 
 
-
Special attributes

+
Special attributes

 
DocNet supports special attributes for Links and Images. Currently this is supported on normal links/image specifications only, e.g.:

 
![id text](imageurl){.cssclass1 .cssclass2 #idvalue name=value}
 
which will result in:

 
<img src="imageurl" alt="id text" id="idvalue" class="cssclass1 cssclass2" name="value" />
 

 
-
Image rendering

+
Image rendering

 
By default images have no special rendering applied to them. To apply a shadow, specify '.shadowed' as css class in a special attribute specification. 
 If you want to have an image rendered centered with a note below it, simply specify a title for the image: 

 
![](mycenteredpicture.jpg "this is a picture")
@@ -169,12 +169,12 @@ If you want to have an image rendered centered with a note below it, simply spec
 

 
 
All images rendered contain the width/height of the picture file included in the html.

-
Abbreviations

+
Abbreviations

 
There's also support for abbreviations, using the <abbr> HTML tag. 

 
Specifying:

 
*[FuBar]: F**ked Up Beyond Any Repair.
 
gives an abbreviation link in the following sentence: This is a test for abbreviations: FuBar.

-
Highlighting code

+
Highlighting code

 
The markdown parser has been extended with GitHub code specifications, so it's easy to specify a specific code beautifying based on a language. This feature uses the Highlight.js javascript library and most popular languages are included. 

 
Example: to specify a codeblock as C#, append cs after the first ``` marker:

 
var i=42;
@@ -182,7 +182,7 @@ If you want to have an image rendered centered with a note below it, simply spec
 
 
To specify a block of text in a fixed sized font but not specify any language highlighting, specify nohighlight as language name:

 
this is a simple <pre> block
-
Linking

+
Linking

 
Docnet doesn't transform links. This means that any link to any document in your documentation has to use the url it will get in the destination folder. Example: you want to link to the file How to\AddEntity.md from a page. In the result site this should be the link How%20to/AddEntity.htm, which you should specify in your markdown. In the future it might be docnet will be updated with link transformation, at the moment it doesn't convert any links besides the usual markdown ones. The markdown parser also doesn't allow spaces to be present in the urls. If you need a space in the url, escape it with %20. 

 
 

diff --git a/search.htm b/search.htm
index 84bfd16..5328a77 100644
--- a/search.htm
+++ b/search.htm
@@ -70,7 +70,7 @@
                 

                 

                     

-
Search

+
Search

 
Docnet will generate a search_data.json file in the root of the destination folder which is used with the javascript based search. It's a simple text search which can locate pages based on the word/sentence specified and will list them in first come first served order. For general purposes of locating a general piece of documentation regarding a topic it's good enough.

 
NOTE: Search locally on a file:/// served site won't work in Chrome, due to cross-origin protection because the search loads the search index and a template from disk in javascript. Either use Firefox or use the site with a server.

 
diff --git a/themes.htm b/themes.htm
index 3617514..e8378c3 100644
--- a/themes.htm
+++ b/themes.htm
@@ -82,13 +82,13 @@
                 

                 

                     

-
Themes

+
Themes

 
Docnet uses themes to produce output in a certain form. A theme is a folder within the Themes folder which contains a PageTemplate.htm file and a Destination folder which contains zero or more folders and files which have to be copied to the Destination folder specified in the docnet.json file. 

-
Themes folder

+
Themes folder

 
Docnet expects the Themes folder to be located in the folder where the executable is started from. This means that if you build Docnet from source, you have to manually copy the Themes folder to the folder your binary is located. To make development easier, you could create a junction in the bin\debug or bin\release folder to the Themes folder in the source repository, using mklink on a windows command prompt.

-
Default theme

+
Default theme

 
The default theme is called Default and is chosen if no theme has been specified in the docnet.json file. It is based on the theme from ReadTheDocs, and is created from the one shipped with MkDocs.

-
PageTemplate.htm

+
PageTemplate.htm

 
The PageTemplate.htm file is a simple HTML file, located in each theme folder, which is used as the template for all generated .htm files. You can place whatever you like in there, including references to css/js files, headers, footers etc. DocNet however expects a couple of markers which are replaced with the data created from the markdown files. These markers are described below. The markers have to be specified as-is.

 
    
 
  • {{Name}}. This is replaced with the value specified in Name in the docnet.json file.
    • 
diff --git a/usage.htm b/usage.htm
index 0665d3a..6d7d40d 100644
--- a/usage.htm
+++ b/usage.htm
@@ -72,7 +72,7 @@
                 

                 

                     

-
Usage

+
Usage

 
The usage is simple:

 
docnet options folder

 
options can be:

@@ -81,7 +81,7 @@
 
 
By default docnet doesn't remove any file in the destination folder. When specified it will remove all files and folders recursively in the specified Destination folder in the found docnet.json. So use this option with caution, as it won't check whether this is the folder your family photos or precious sourcecode are located! 

 
folder is the folder where a docnet.json file is expected to be present. 

-
Requirements

+
Requirements

 
Docnet is a .NET full application (using .NET 4.6.1) and requires .NET full to run. Not tested on Mono but it's highly likely it works on Mono without a problem. The code uses .NET 4.6.1 but it can be compiled against lower versions of .NET full, it doesn't use .NET 4.6 specific features but as Microsoft supports only the latest .NET 4.x versions, it was a logical choice to use .NET 4.6.1.