From e4f6b5ae59d955b99faa9b0d088755ca66a26b8b Mon Sep 17 00:00:00 2001 From: Frans Bouma Date: Mon, 5 Jun 2017 17:03:45 +0200 Subject: [PATCH] Updated docs for PR #52: auto convert local links --- MarkdownSource/docnet.json | 1 + MarkdownSource/docnetjson.md | 2 ++ MarkdownSource/markdownsupport.md | 7 ++++++- docnetjson.htm | 2 ++ markdownextensions.htm | 4 ++-- markdownsupport.htm | 6 ++++-- search_index.json | 4 ++-- 7 files changed, 19 insertions(+), 7 deletions(-) diff --git a/MarkdownSource/docnet.json b/MarkdownSource/docnet.json index 955a0ed..9ce6b5e 100644 --- a/MarkdownSource/docnet.json +++ b/MarkdownSource/docnet.json @@ -5,6 +5,7 @@ "IncludeSource": "Includes", "Theme" : "Default", "Footer" : "Made with DocNet. Get your copy at: https://github.com/FransBouma/DocNet.", + "ConvertLocalLinks": "true", "Pages" : { "__index" : "index.md", diff --git a/MarkdownSource/docnetjson.md b/MarkdownSource/docnetjson.md index e735ee2..a152c4c 100644 --- a/MarkdownSource/docnetjson.md +++ b/MarkdownSource/docnetjson.md @@ -12,6 +12,7 @@ DocNet uses a json file to determine what to do in what form. The format is stra "Theme" : "themefolder", "SourceFoldersToCopy" : ["folder1", "foldern"], "Footer" : "footer text or HTML", + "ConvertLocalLinks: "true" | "false", "Pages" : { "__index" : "index.md", @@ -35,6 +36,7 @@ The order in which the pages are specified is the order in which they'll appear * `IncludeSource` specifies the folder where the files specified to be included using [@@include directives](markdownextensions.htm#include-files) are located. If `IncludeSource` isn't specified, the value `Includes` is assumed. * `Theme` specifies the folder within the `Themes` folder in the folder the `docnet` executable is located which is used as the theme for the pages to generate. `Docnet` expects a file called `PageTemplate.htm` within the specified `Theme` folder, which contains the HTML which is used as the wrapper file for the HTML generated from the markdown. It has to contain a couple of marker, which are described later in this document. If `Theme` isn't specified, `Default` is assumed. * `SourceFoldersToCopy`. This is an optional directive with, if specified, one or more folder names relative to `Source`, which contain files to copy to the `Destination` folder. E.g. image files used in the markdown files, located in an `Images` folder can be copied this way to the output folder reliably. All folders specified are copied recursively. +* `ConvertLocalLinks`. This is an optional directive which, if specified and set to `"true"`, will make DocNet convert all local links to `.md` suffixed files into `.htm` files. Example: `(local link)[somemarkdownfile.md]` will be converted to `local link`. Non-local urls are not converted. Default: `"false"`. * `Footer`. This is text and/or HTML which is placed in the footer of each page, using a _marker_ (see below). * `Pages` contains the pages to generate into the output, in the order and structure in which you want them to appear in the navigation. The name given is the value used in the navigation tree and has to be unique per level. The value specified with each name is the markdown file to load, parse and generate as .htm file in the output. The markdown file is relative to the path specified in `Source`. A file `foo.md` will be generated as `foo.htm` in the output. diff --git a/MarkdownSource/markdownsupport.md b/MarkdownSource/markdownsupport.md index b6491b1..e763b1d 100644 --- a/MarkdownSource/markdownsupport.md +++ b/MarkdownSource/markdownsupport.md @@ -114,6 +114,11 @@ this is a simple 
 block
 ```
 
 ##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`. 
+`Docnet` doesn't automatically transform links to markdown files by default. To enable automatic link conversion to local markdown files, please specify the `ConvertLocalLinks` option in the [docnet.json file](docnetjson.md) file with the value `true`. If `ConvertLocalLinks` isn't specified or set to `false`, 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. If `ConvertLocalLinks` isn't specified or set to `false`, you have to specify in the markdown the url it will need to be in the result site, which is the link `How%20to/AddEntity.htm`. If `ConvertLocalLinks` is set to `true`, you can specify `How%20to/AddEntity.md` and DocNet will convert it to `How%20to/AddEntity.htm`.
+
+@alert important
+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`. 
+@end
 
diff --git a/docnetjson.htm b/docnetjson.htm
index ffded52..05625d3 100644
--- a/docnetjson.htm
+++ b/docnetjson.htm
@@ -89,6 +89,7 @@
     "Theme" : "themefolder",
     "SourceFoldersToCopy" : ["folder1", "foldern"],
     "Footer" : "footer text or HTML",
+    "ConvertLocalLinks: "true" | "false",
     "Pages" : 
     {
         "__index" : "index.md",
@@ -112,6 +113,7 @@
 
  • IncludeSource specifies the folder where the files specified to be included using @@include directives are located. If IncludeSource isn't specified, the value Includes is assumed. 
    • 
 
  • Theme specifies the folder within the Themes folder in the folder the docnet executable is located which is used as the theme for the pages to generate. Docnet expects a file called PageTemplate.htm within the specified Theme folder, which contains the HTML which is used as the wrapper file for the HTML generated from the markdown. It has to contain a couple of marker, which are described later in this document. If Theme isn't specified, Default is assumed.
    • 
 
  • SourceFoldersToCopy. This is an optional directive with, if specified, one or more folder names relative to Source, which contain files to copy to the Destination folder. E.g. image files used in the markdown files, located in an Images folder can be copied this way to the output folder reliably. All folders specified are copied recursively.
    • 
+
  • ConvertLocalLinks. This is an optional directive which, if specified and set to "true", will make DocNet convert all local links to .md suffixed files into .htm files. Example: (local link)[somemarkdownfile.md] will be converted to <a href="somemarkdownfile.htm">local link</a>. Non-local urls are not converted. Default: "false". 
    • 
 
  • Footer. This is text and/or HTML which is placed in the footer of each page, using a marker (see below).
    • 
 
  • Pages contains the pages to generate into the output, in the order and structure in which you want them to appear in the navigation. The name given is the value used in the navigation tree and has to be unique per level. The value specified with each name is the markdown file to load, parse and generate as .htm file in the output. The markdown file is relative to the path specified in Source. A file foo.md will be generated as foo.htm in the output. 
    • 
 
diff --git a/markdownextensions.htm b/markdownextensions.htm
index 2940479..2981d91 100644
--- a/markdownextensions.htm
+++ b/markdownextensions.htm
@@ -229,9 +229,9 @@ The files to include are read from a special folder, specified under Inclu
 specified in the docnet.json file, the folder Includes is assumed. 
    
 
    The directive @@include("somehtmlinclude.htm")
    
 
    results in the contents of somehtmlinclude.htm being included at the spot where the @@include statement is given, as shown below:
    
-
    This is an included piece of html
    
+
    @@include("includedhtml.htm")
    
 
    You can also include markdown, which is then processed with the other markdown as if it's part of it. 
    
-
    This is an included piece of Markdown.
    
+
    @@include("includedmarkdown.md")
    
 
                     
                 
diff --git a/markdownsupport.htm b/markdownsupport.htm
index 3dd38d9..b52f758 100644
--- a/markdownsupport.htm
+++ b/markdownsupport.htm
@@ -183,8 +183,10 @@ 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
    
-
    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. 
    
-
+
    Docnet doesn't automatically transform links to markdown files by default. To enable automatic link conversion to local markdown files, please specify the ConvertLocalLinks option in the docnet.json file file with the value true. If ConvertLocalLinks isn't specified or set to false, 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. If ConvertLocalLinks isn't specified or set to false, you have to specify in the markdown the url it will need to be in the result site, which is the link How%20to/AddEntity.htm. If ConvertLocalLinks is set to true, you can specify How%20to/AddEntity.md and DocNet will convert it to How%20to/AddEntity.htm.
    
+
     Important!
    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_index.json b/search_index.json
index 612ecab..7bf6059 100644
--- a/search_index.json
+++ b/search_index.json
@@ -9,7 +9,7 @@
     {
       "location": "docnetjson.htm",
       "breadcrumbs": "Home / Configuration / Site configuration with the docnet.json file",
-      "keywords": "__index _marker_ _Sub 1 1_ 2 3 4 a A above absolute all All always an and appear are as assigned assumed be becomes below but called can case characters clicked configuration contain contains content copied copy couple create default Default defined described Destination destinationfolder determine directive directives do docnet Docnet DocNet document doesn e E each Each elements entry escape example executable exist exists expected expects file filename_page1 filename_page2 filename_page3 filename_page4 filenames files folder folder1 foldern folders foo footer Footer for form format forward from full g generate generated given guarantees has have header Header Home htm HTML if If image Images in include included includefolder Includes IncludeSource index into is isn it It json later level Levels list load loaded located markdown markdownextensions marker md more name Name nameoflevel names navigated navigation no of one only optional or order output page Page pages Pages PageTemplate parent parse path Paths per placed recursively relative reliably root same see See sensitive shown simply site so Source sourcefolder SourceFoldersToCopy special specified specifies specify starting still straight structure sub Sub subfolders target text the The them theme Theme themefolder Themes there they this This Title to topics topictitle tree unique use used uses using value want way what when where which will with within without wrapper written you",
+      "keywords": "__index _marker_ _Sub 1 1_ 2 3 4 a A above absolute all All always an and appear are as assigned assumed be becomes below but called can case characters clicked configuration contain contains content convert converted ConvertLocalLinks copied copy couple create default Default defined described Destination destinationfolder determine directive directives do docnet Docnet DocNet document doesn e E each Each elements entry escape example Example executable exist exists expected expects false file filename_page1 filename_page2 filename_page3 filename_page4 filenames files folder folder1 foldern folders foo footer Footer for form format forward from full g generate generated given guarantees has have header Header Home href htm HTML if If image Images in include included includefolder Includes IncludeSource index into is isn it It json later level Levels link links list load loaded local located make markdown markdownextensions marker md more name Name nameoflevel names navigated navigation no Non not of one only optional or order output page Page pages Pages PageTemplate parent parse path Paths per placed recursively relative reliably root same see See sensitive set shown simply site so somemarkdownfile Source sourcefolder SourceFoldersToCopy special specified specifies specify starting still straight structure sub Sub subfolders suffixed target text the The them theme Theme themefolder Themes there they this This Title to topics topictitle tree true unique urls use used uses using value want way what when where which will with within without wrapper written you",
       "title": "Site configuration with the docnet.json file"
     },
     {
@@ -27,7 +27,7 @@
     {
       "location": "markdownsupport.htm",
       "breadcrumbs": "Home / Authoring content / Writing content using Markdown / Markdown support",
-      "keywords": "1 2 20 20to 42 a A abbr abbreviation abbreviations Abbreviations above actual added AddEntity Additionally after all All allow also alt an and And any Any append Apples applied apply are as at attribute attributes Bananas based basic be beach beautifying been below besides Beyond bit block Bongo bottom but by By C ca called can centered class Click code codeblock color Color com comes contain convert couple cs css cssclass1 cssclass2 Currently daringfireball default define defined defining definition Definition described description destination div do docnet Docnet DocNet document documentation doesn e easy escape example Example examples extended extensions extra Extra extramode F feature figure file files first fixed folder following font footnote footnotes Footnotes for FransBouma from Fruit FuBar full future g get github GitHub given gives go going Green Gruber has have height Hey Highlight highlighting Highlighting highlightjs how How htm html HTML http https i id idvalue If image Image images Images imageurl img in In included input is it It item Item javascript John jpg js ked know language languages library like link Linking links Links lists look markdown Markdown markdowndeep MarkdownDeep MarkdownDeepTests marker markers master md means michelf might minute moment more most mycenteredpicture name neat need net no nohighlight normal not note of oh on one ones only org p page parsed parser Pears php Php PHP picture Please popular pre present projects Red related rendered rendering Repair respository result results sea see sentence set shadow shadowed should simple simply site sized so software space spaces special Special specific specification specifications specified specify Specifying src standard Standard statements strange style superscript support supported supports syntax system tables Tables tag test testfiles text that the The them then There this This through title to To too topten toptensoftware transform transformation tree Two unit Up updated url urls use uses using usual value values var want well Where which width will wind with writing www xxx Yellow you You your yyy",
+      "keywords": "1 2 20 20to 42 a A abbr abbreviation abbreviations Abbreviations above actual added AddEntity Additionally after alert all All allow also alt an and And any Any append Apples applied apply are as at attribute attributes automatic automatically Bananas based basic be beach beautifying been below Beyond bit block Bongo bottom but by By C ca called can centered class Click code codeblock color Color com comes contain conversion convert ConvertLocalLinks couple cs css cssclass1 cssclass2 Currently daringfireball default define defined defining definition Definition described description destination div do docnet Docnet DocNet docnetjson document documentation doesn e easy enable end escape example Example examples extended extensions extra Extra extramode F false feature figure file files first fixed folder following font footnote footnotes Footnotes for FransBouma from Fruit FuBar full g get github GitHub given gives go going Green Gruber has have height Hey Highlight highlighting Highlighting highlightjs how How htm html HTML http https i id idvalue If image Image images Images imageurl img important in included input is isn it It item Item javascript John jpg js json ked know language languages library like link Linking links Links lists local look markdown Markdown markdowndeep MarkdownDeep MarkdownDeepTests marker markers master md michelf minute more most mycenteredpicture name neat need net no nohighlight normal not note of oh on one only option or org p page parsed parser Pears php Php PHP picture please Please popular pre present projects Red related rendered rendering Repair respository result results sea see sentence set shadow shadowed simple simply site sized so software space spaces special Special specific specification specifications specified specify Specifying src standard Standard statements strange style superscript support supported supports syntax system tables Tables tag test testfiles text the The them then There this This through title to To too topten toptensoftware transform tree true Two unit Up url urls use uses using value values var want well Where which width will wind with writing www xxx Yellow you You your yyy",
       "title": "Markdown support"
     },
     {