From 4b86cebef2fc8b9baaec6db54ec2f125836561a0 Mon Sep 17 00:00:00 2001 From: Frans Bouma Date: Wed, 9 Mar 2016 13:29:39 +0100 Subject: [PATCH] Documented @@include directive --- Authoringcontent.htm | 2 +- Configuration.htm | 2 +- MarkdownSource/docnet.json | 1 + MarkdownSource/docnetjson.md | 2 ++ MarkdownSource/markdownextensions.md | 15 +++++++++++++++ WritingcontentusingMarkdown.htm | 2 +- docnetjson.htm | 2 ++ markdownextensions.htm | 12 +++++++++++- search_index.json | 4 ++-- 9 files changed, 36 insertions(+), 6 deletions(-) diff --git a/Authoringcontent.htm b/Authoringcontent.htm index f3314c8..07fe728 100644 --- a/Authoringcontent.htm +++ b/Authoringcontent.htm @@ -79,7 +79,7 @@

Authoring content

-

Please select one of the topic in this section:

+

Please select one of the topics in this section:

  • Themes
  • Writing content using Markdown
    • diff --git a/Configuration.htm b/Configuration.htm index 0788d1b..298f49a 100644 --- a/Configuration.htm +++ b/Configuration.htm @@ -78,7 +78,7 @@

    Configuration

    -

    Please select one of the topic in this section:

    +

    Please select one of the topics in this section:

    • Site configuration with the docnet.json file
    • Automatic H2 level ToC entry discovery
      • diff --git a/MarkdownSource/docnet.json b/MarkdownSource/docnet.json index b94b0c4..955a0ed 100644 --- a/MarkdownSource/docnet.json +++ b/MarkdownSource/docnet.json @@ -2,6 +2,7 @@ "Name" : "DocNet Documentation", "Source" : ".", "Destination" : "..\\", + "IncludeSource": "Includes", "Theme" : "Default", "Footer" : "Made with DocNet. Get your copy at: https://github.com/FransBouma/DocNet.", "Pages" : diff --git a/MarkdownSource/docnetjson.md b/MarkdownSource/docnetjson.md index 32d1358..e735ee2 100644 --- a/MarkdownSource/docnetjson.md +++ b/MarkdownSource/docnetjson.md @@ -8,6 +8,7 @@ DocNet uses a json file to determine what to do in what form. The format is stra "Name" : "name of site", "Source" : "sourcefolder", "Destination" : "destinationfolder", + "IncludeSource": "includefolder", "Theme" : "themefolder", "SourceFoldersToCopy" : ["folder1", "foldern"], "Footer" : "footer text or HTML", @@ -31,6 +32,7 @@ The order in which the pages are specified is the order in which they'll appear * `Name` specifies the name of the site to generate. * `Source` specifies the root of the tree of folders in which markdown files are expected. `sourcefolder` can be a relative path or an absolute path and is used as the root folder for filenames specified in `Pages`. * `Destination` specifies the folder where the output will be written to (.htm files). The output will be written to this folder only, all files from subfolders in `Source` will be written to the folder specified in `Destination`. with the same structure as the *navigation* in `Pages`. `destinationfolder` can be a relative path or an absolute path. +* `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. * `Footer`. This is text and/or HTML which is placed in the footer of each page, using a _marker_ (see below). diff --git a/MarkdownSource/markdownextensions.md b/MarkdownSource/markdownextensions.md index 4cfb4d7..79cfd15 100644 --- a/MarkdownSource/markdownextensions.md +++ b/MarkdownSource/markdownextensions.md @@ -116,3 +116,18 @@ Now, the second tab however is very interesting. At least let's pretend it is! @end @endtabs +##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 +specified in the [docnet.json](docnetjson.htm) 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: + +@@include("includedhtml.htm") + +You can also include markdown, which is then processed with the other markdown as if it's part of it. + +@@include("includedmarkdown.md") + diff --git a/WritingcontentusingMarkdown.htm b/WritingcontentusingMarkdown.htm index 3f8c58e..58930ba 100644 --- a/WritingcontentusingMarkdown.htm +++ b/WritingcontentusingMarkdown.htm @@ -86,7 +86,7 @@

      Writing content using Markdown

      -

      Please select one of the topic in this section:

      +

      Please select one of the topics in this section:

      • Markdown support
      • DocNet Markdown extensions
        • diff --git a/docnetjson.htm b/docnetjson.htm index 08a3ea0..a1dc029 100644 --- a/docnetjson.htm +++ b/docnetjson.htm @@ -85,6 +85,7 @@ "Name" : "name of site", "Source" : "sourcefolder", "Destination" : "destinationfolder", + "IncludeSource": "includefolder", "Theme" : "themefolder", "SourceFoldersToCopy" : ["folder1", "foldern"], "Footer" : "footer text or HTML", @@ -108,6 +109,7 @@
      • Name specifies the name of the site to generate.
      • Source specifies the root of the tree of folders in which markdown files are expected. sourcefolder can be a relative path or an absolute path and is used as the root folder for filenames specified in Pages.
      • Destination specifies the folder where the output will be written to (.htm files). The output will be written to this folder only, all files from subfolders in Source will be written to the folder specified in Destination. with the same structure as the navigation in Pages. destinationfolder can be a relative path or an absolute path.
        • +
      • 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.
      • Footer. This is text and/or HTML which is placed in the footer of each page, using a marker (see below).
        • diff --git a/markdownextensions.htm b/markdownextensions.htm index 49b3f1a..74b5840 100644 --- a/markdownextensions.htm +++ b/markdownextensions.htm @@ -51,6 +51,7 @@
      • Alert boxes
      • Font Awesome icons
      • Tabs
        • +
      • Include files
    @@ -145,7 +146,16 @@ 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

    +

    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.

    +

    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

    +

    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.

    +