diff --git a/MarkdownSource/acknowledgements.md b/MarkdownSource/acknowledgements.md index 27b9196..d5d3db9 100644 --- a/MarkdownSource/acknowledgements.md +++ b/MarkdownSource/acknowledgements.md @@ -6,3 +6,4 @@ This application wouldn't be possible without the work of others. The (likely in * [MkDocs](http://www.mkdocs.org/). `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. * [MarkdownDeep](http://www.toptensoftware.com/markdowndeep/). The markdown parser is an extended version of the `MarkdownDeep` parser from topten software. * [Json.NET](http://www.newtonsoft.com/json). The reading/writing of json files is important for `Docnet` and it uses Json.NET for that. +* [ProjBook](http://defrancea.github.io/Projbook/). The snippet extraction code in `DocNet` is based on ProjBook's extractors. \ No newline at end of file diff --git a/MarkdownSource/docnet.json b/MarkdownSource/docnet.json index 955a0ed..d268a83 100644 --- a/MarkdownSource/docnet.json +++ b/MarkdownSource/docnet.json @@ -3,7 +3,7 @@ "Source" : ".", "Destination" : "..\\", "IncludeSource": "Includes", - "Theme" : "Default", + "Theme" : "Light", "Footer" : "Made with DocNet. Get your copy at: https://github.com/FransBouma/DocNet.", "Pages" : { diff --git a/MarkdownSource/markdownextensions.md b/MarkdownSource/markdownextensions.md index 79cfd15..ecded4d 100644 --- a/MarkdownSource/markdownextensions.md +++ b/MarkdownSource/markdownextensions.md @@ -116,6 +116,27 @@ Now, the second tab however is very interesting. At least let's pretend it is! @end @endtabs + +##Snippets +You can include snippets from other files as fenced code blocks using the directive `@snippet` which has the following syntax: + +`@snippet language [file specification] pattern` + +Here, _language_ can be one of `cs`, `txt` or `xml`. If an unknown language is specified, `txt` is chosen. _Pattern_ is used to determine which part of the file specified between `[]` +is to be embedded at the spot of the `@snippet` fragment. This code is based on [Projbook's extractor feature](http://defrancea.github.io/Projbook/projbook.html#Pageextractormd) and follows the same pattern system. + +Below, the method `GenerateToCFragment` is embedded in a C# fenced code block. This method is a DocNet method and is obtained directly from the source code. This shows the `@snippet` +feature's power as it keeps the documentation in sync with the embedded code without the necessity of updating things. + +The following snippet, if the DocNet sourcecode is located at the spot reachable by the path below: + +```nohighlight +@snippet cs [../../DocNet/src/DocNet/NavigationLevel.cs] GenerateToCFragment +``` + +will result in: +@snippet cs [../../DocNet/src/DocNet/NavigationLevel.cs] GenerateToCFragment + ##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](docnetjson.htm) file. If no `IncludeSource` directive is diff --git a/acknowledgements.htm b/acknowledgements.htm index 5f1ae33..8d9ba9f 100644 --- a/acknowledgements.htm +++ b/acknowledgements.htm @@ -76,6 +76,7 @@
  • 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.
  • MarkdownDeep. The markdown parser is an extended version of the MarkdownDeep parser from topten software.
  • Json.NET. The reading/writing of json files is important for Docnet and it uses Json.NET for that.
    • +
  • ProjBook. The snippet extraction code in DocNet is based on ProjBook's extractors.
    • diff --git a/css/theme_colors.css b/css/theme_colors.css index b462a69..adbe734 100644 --- a/css/theme_colors.css +++ b/css/theme_colors.css @@ -16,7 +16,7 @@ a:visited { } body { - color: #404040; + color: #222; } code, pre.nocode { @@ -58,7 +58,7 @@ mark { } .toc-footer hr { - border-color: #3e3a3a; + border-color: #ccc; } /* #endregion */ @@ -182,44 +182,43 @@ mark { } .menu-vertical ul.currentrelative, .menu-vertical ul.currentrelativeroot { - background-color: #e3e3e3; + background-color: #fcfcfc; } .menu-vertical li.current { - background-color: #fff; + background-color: #fcfcfc; } .menu-vertical ul.current { - background-color: #3e3a3a; + background-color: #fcfcfc; } .menu-vertical li.current a { - color: #777; + color: #6b6b6b; } .menu-vertical li.current.tocentry > a, .menu-vertical li.current > a { - color: #444; + color: #6b6b6b; } .menu-vertical li.current.tocentry ul li > a { - color: #777; + color: #6b6b6b; } .menu-vertical a { - color: #ccc; + color: #6b6b6b; } .menu-vertical a:hover, .menu-vertical li.on a:hover { - color: #ccc; + color: #999; } - .menu-vertical span, .menu-vertical span > a { - color: #999; + color: #6b6b6b; } .nav-side { - background: #343131; + background: #eee; } .nav-top { diff --git a/markdownextensions.htm b/markdownextensions.htm index 0f5dbff..2940479 100644 --- a/markdownextensions.htm +++ b/markdownextensions.htm @@ -51,6 +51,7 @@
  • Alert boxes
  • Font Awesome icons
  • Tabs
    • +
  • Snippets
  • Include files
    • @@ -146,7 +147,83 @@ 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

    +

    Snippets

    +

    You can include snippets from other files as fenced code blocks using the directive @snippet which has the following syntax:

    +

    @snippet language [file specification] pattern

    +

    Here, language can be one of cs, txt or xml. If an unknown language is specified, txt is chosen. Pattern is used to determine which part of the file specified between [] +is to be embedded at the spot of the @snippet fragment. This code is based on Projbook's extractor feature and follows the same pattern system.

    +

    Below, the method GenerateToCFragment is embedded in a C# fenced code block. This method is a DocNet method and is obtained directly from the source code. This shows the @snippet +feature's power as it keeps the documentation in sync with the embedded code without the necessity of updating things.

    +

    The following snippet, if the DocNet sourcecode is located at the spot reachable by the path below:

    +
    @snippet cs [../../DocNet/src/DocNet/NavigationLevel.cs] GenerateToCFragment
+

    will result in:

    +
    /// <summary>
+/// Generates the ToC fragment for this element, which can either be a simple line or a full expanded menu.
+/// </summary>
+/// <param name="navigatedPath">The navigated path to the current element, which doesn't necessarily have to be this element.</param>
+/// <param name="relativePathToRoot">The relative path back to the URL root, e.g. ../.., so it can be used for links to elements in this path.</param>
+/// <returns></returns>
+public override string GenerateToCFragment(NavigatedPath navigatedPath, string relativePathToRoot)
+{
+    var fragments = new List<string>();
+    if(!this.IsRoot)
+    {
+        fragments.Add("<li class=\"tocentry\">");
+    }
+    if(navigatedPath.Contains(this))
+    {
+        // we're expanded. If we're not root and on the top of the navigated path stack, our index page is the page we're currently generating the ToC for, so 
+        // we have to mark the entry as 'current'
+        if(navigatedPath.Peek() == this && !this.IsRoot)
+        {
+            fragments.Add("<ul class=\"current\">");
+        }
+        else
+        {
+            fragments.Add("<ul>");
+        }
+
+        // first render the level header, which is the index element, if present or a label. The root always has an __index element otherwise we'd have stopped at load.
+        var elementStartTag = "<li><span class=\"navigationgroup\"><i class=\"fa fa-caret-down\"></i> ";
+        var indexElement = this.IndexElement;
+        if(indexElement == null)
+        {
+            fragments.Add(string.Format("{0}{1}</span></li>", elementStartTag, this.Name));
+        }
+        else
+        {
+            if(this.IsRoot)
+            {
+                fragments.Add(indexElement.PerformGenerateToCFragment(navigatedPath, relativePathToRoot));
+            }
+            else
+            {
+                fragments.Add(string.Format("{0}<a href=\"{1}{2}\">{3}</a></span></li>", elementStartTag, relativePathToRoot, HttpUtility.UrlPathEncode(indexElement.TargetURL), 
+                                            this.Name));
+            }
+        }
+        // then the elements in the container. Index elements are skipped here.
+        foreach(var element in this.Value)
+        {
+            fragments.Add(element.GenerateToCFragment(navigatedPath, relativePathToRoot));
+        }
+        fragments.Add("</ul>");
+    }
+    else
+    {
+        // just a link
+        fragments.Add(string.Format("<span class=\"navigationgroup\"><i class=\"fa fa-caret-right\"></i> <a href=\"{0}{1}\">{2}</a></span>", 
+                                    relativePathToRoot, HttpUtility.UrlPathEncode(this.TargetURL), this.Name));
+    }
+    if(!this.IsRoot)
+    {
+        fragments.Add("</li>");
+    }
+    return string.Join(Environment.NewLine, fragments.ToArray());
+}
+
    + +

    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/search_index.json b/search_index.json index 0310f73..612ecab 100644 --- a/search_index.json +++ b/search_index.json @@ -33,7 +33,7 @@ { "location": "markdownextensions.htm", "breadcrumbs": "Home / Authoring content / Writing content using Markdown / DocNet Markdown extensions", - "keywords": "_iconname_ 64 a add after alert Alert alerts also an and are as As assumed at At awesome Awesome based be being below Below Between blue box boxes by can Close codepen contents control converted create CSS3 danger dangerous deal define defined defines definition directive displayed docnet Docnet DocNet docnetjson documentation each easier easy element end End endtabs example Example examples extensions fa file filename files first First folder followed following font Font for from fusco Fusco github GitHub given however htm HTML http icon iconname icons if If important in include Include included includedhtml includedmarkdown Includes IncludeSource info interesting into io is isn it It Joseph json label least let make markdown Markdown md more name need neutral newline newlines no nohighlight nothing Now of on one or other part pen pretend processed pure quickly read recursive red result results Results second Second see set shown shows simple somehtmlinclude special specified specify spot start statement statements suffixed system tab Tab tabs Tabs text that the The them then This those Three tip to To two type types under use used using very warning well where which will with work writing Wvzjrm yellow you You your", + "keywords": "_iconname_ _language_ _Pattern_ 64 a add after alert Alert alerts also an and are as As assumed at At awesome Awesome based be being below Below between Between block blocks blue box boxes by C can chosen Close code codepen contents control converted create cs CSS3 danger dangerous deal define defined defines definition defrancea determine directive directly displayed docnet Docnet DocNet docnetjson documentation each easier easy element embedded end End endtabs example Example examples extensions extractor fa feature fenced file filename files first First folder followed following follows font Font for fragment from fusco Fusco GenerateToCFragment github GitHub given has Here however htm html HTML http icon iconname icons if If important in include Include included includedhtml includedmarkdown Includes IncludeSource info interesting into io is isn it It Joseph json keeps label language least let located make markdown Markdown md method more name NavigationLevel necessity need neutral newline newlines no nohighlight nothing Now obtained of on one or other Pageextractormd part path pattern pen power pretend processed projbook Projbook pure quickly reachable read recursive red result results Results same second Second see set shown shows simple snippet snippets Snippets somehtmlinclude source sourcecode special specification specified specify spot src start statement statements suffixed sync syntax system tab Tab tabs Tabs text that the The them then things This those Three tip to To two txt type types under unknown updating use used using very warning well where which will with without work writing Wvzjrm xml yellow you You your", "title": "DocNet Markdown extensions" }, { @@ -45,7 +45,7 @@ { "location": "acknowledgements.htm", "breadcrumbs": "Home / Acknowledgements", - "keywords": "a Acknowledgements an and application as based be below borrows builds cleaned com contains css deal Docnet extended files for from great http important incomplete is it javascript json Json likely list markdown markdowndeep MarkdownDeep mkdocs MkDocs NET newtonsoft of on org others parser possible reading Readthedocs search software that the The their theme This topten toptensoftware up upon uses version well without work wouldn writing www", + "keywords": "a Acknowledgements an and application as based be below borrows builds cleaned code com contains css deal defrancea Docnet DocNet extended extraction extractors files for from github great http important in incomplete io is it javascript json Json likely list markdown markdowndeep MarkdownDeep mkdocs MkDocs NET newtonsoft of on org others parser possible Projbook ProjBook reading Readthedocs search snippet software that the The their theme This topten toptensoftware up upon uses version well without work wouldn writing www", "title": "Acknowledgements" }, {