Documented content transclusion. * Closes #51.
h3rald h3rald@h3rald.com
Sat, 11 Mar 2017 17:08:37 +0100
7 files changed,
55 insertions(+),
17 deletions(-)
M
README.md
→
README.md
@@ -1,5 +1,3 @@
-[](https://github.com/h3rald/hastyscribe) - [](https://github.com/h3rald/hastyscribe) [](https://raw.githubusercontent.com/h3rald/hastyscribe/master/LICENSE) [](https://travis-ci.org/h3rald/hastyscribe)
M
build_guide
→
build_guide
@@ -1,1 +1,1 @@
-./hastyscribe doc/HastyScribe_UserGuide.md --field/version=1.5.0 +./hastyscribe doc/HastyScribe_UserGuide.md --field/version=1.6.0
M
doc/-overview.md
→
doc/-overview.md
@@ -25,7 +25,7 @@
> %tip% > Tip > -> You can learn about Markdown syntax in the [Syntax Reference](#Syntax.Reference) section of this document. Alternatively, you can also read the original [Markdown syntax page][md-syntax] on John Gruber's blog, Daring Fireball. +> You can learn about Markdown syntax in the [Syntax Reference](#Syntax-Reference) section of this document. Alternatively, you can also read the original [Markdown syntax page][md-syntax] on John Gruber's blog, Daring Fireball. ### Discount Extensions@@ -43,6 +43,9 @@ ### Custom Fields
{{hs}} also supports [fields](#Fields) to easily include things like the current date or time, but also custom values specified as command-line parameters. +### Content Transclusion + +When managing long documents, you can take advantage of {{hs}}'s [transclusion](#Transclusion) support to split your content into several files, and transclude them as you see fit. ### Substitution Macros
M
doc/-syntax.md
→
doc/-syntax.md
@@ -16,6 +16,19 @@ >
> * The order of the document headers is significant. > * If you want to use the current date, enter [% -](class:kwd) in the third line. +## Transclusion + +When writing a long document, it is often useful to split it into many different files, to manage its contents better. {{hs}} provides basic content transclusion support through the following syntax: + +<code>\{@ my-file.md || 1 @\}</code> + +When a file is processed, the line above will cause the contents of file [my-file.md](class:file) to be included in the current file, as if they were part of it. Additionally, when using content transclusion syntax, it is mandatory to specify a number between 0 and 5 to indicate the _offset_ of the headings present in the transcluded file. In this example, the heading numbers of all headings present in [my-file.md](class:file) will be increased by 1, so any [h2](class:kwd) will become [h3](class:kwd), any [h3](class:kwd) will become [h4](class:kwd), and so on. + +> %warning% +> Limitations +> +> * It is recommended to place all transcluded files in the same folder as the transcluding file. If a transcluded file includes any image, its relative path will be interpreted as if it was relative to the transcluding file. +> * Heading offset will only work if headings are created using [#](class:kwd)s. Underline syntax for [h1](class:kwd) and [h2](class:kwd) is not supported. ## Snippets
M
doc/HastyScribe_UserGuide.htm
→
doc/HastyScribe_UserGuide.htm
@@ -4355,6 +4355,7 @@ <li><a href="#Standard-Markdown">Standard Markdown</a></li>
<li><a href="#Discount-Extensions">Discount Extensions</a></li> <li><a href="#Text-Snippets">Text Snippets</a></li> <li><a href="#Custom-Fields">Custom Fields</a></li> + <li><a href="#Content-Transclusion">Content Transclusion</a></li> <li><a href="#Substitution-Macros">Substitution Macros</a></li> <li><a href="#Image-(and-font)-Embedding">Image (and font) Embedding</a></li> <li><a href="#FontAwesome-Icons">FontAwesome Icons</a></li>@@ -4383,6 +4384,7 @@ </li>
<li><a href="#Syntax-Reference">Syntax Reference</a> <ul> <li><a href="#Document-Headers">Document Headers</a></li> + <li><a href="#Transclusion">Transclusion</a></li> <li><a href="#Snippets">Snippets</a></li> <li><a href="#Fields">Fields</a></li> <li><a href="#Macros">Macros</a></li>@@ -4466,7 +4468,7 @@ <p>HastyScribe supports standard markdown for formatting text. Markdown is a lightweight markup language created by John Gruber, and used on many web sites and programs to enable users to write HTML code <em>without actually writing HTML tags</em>.</p>
<div class="tip"><p>Tip</p> -<p>You can learn about Markdown syntax in the <a href="#Syntax.Reference">Syntax Reference</a> section of this document. Alternatively, you can also read the original <a href="https://daringfireball.net/projects/markdown/syntax">Markdown syntax page</a> on John Gruber’s blog, Daring Fireball.</p></div> +<p>You can learn about Markdown syntax in the <a href="#Syntax-Reference">Syntax Reference</a> section of this document. Alternatively, you can also read the original <a href="https://daringfireball.net/projects/markdown/syntax">Markdown syntax page</a> on John Gruber’s blog, Daring Fireball.</p></div> <a name="Discount-Extensions"></a> <h4>Discount Extensions<a href="#document-top" title="Go to top"></a></h4>@@ -4490,6 +4492,11 @@ <h4>Custom Fields<a href="#document-top" title="Go to top"></a></h4>
<p>HastyScribe also supports <a href="#Fields">fields</a> to easily include things like the current date or time, but also custom values specified as command-line parameters.</p> +<a name="Content-Transclusion"></a> +<h4>Content Transclusion<a href="#document-top" title="Go to top"></a></h4> + +<p>When managing long documents, you can take advantage of HastyScribe’s <a href="#Transclusion">transclusion</a> support to split your content into several files, and transclude them as you see fit.</p> + <a name="Substitution-Macros"></a> <h4>Substitution Macros<a href="#document-top" title="Go to top"></a></h4>@@ -4539,11 +4546,11 @@
<p>The easiest way to get HastyScribe is by downloading one of the prebuilt binaries from the <a href="https://github.com/h3rald/hastyscribe/releases/download/v">Github Release Page</a>:</p> <ul> -<li><a href="https://github.com/h3rald/hastyscribe/releases/download/v1.5.0/hastyscribe_v1.5.0_macos_x64.zip">HastyScribe for Mac OS X (x64)</a> – Compiled on Mac OS X Sierra (LLVM CLANG 8.0.0)</li> -<li><a href="https://github.com/h3rald/hastyscribe/releases/download/v1.5.0/hastyscribe_v1.5.0_windows_x64.zip">HastyScribe for Windows (x64)</a> – Cross-compiled on Mac OS X Sierra (MinGW-w64 GCC 4.8.2)</li> -<li><a href="https://github.com/h3rald/hastyscribe/releases/download/v1.5.0/hastyscribe_v1.5.0_linux_x64.zip">HastyScribe for Linux (x64)</a> – Cross-compiled on Mac OS X Sierra (GNU GCC 4.8.1)</li> -<li><a href="https://github.com/h3rald/hastyscribe/releases/download/v1.5.0/hastyscribe_v1.5.0_linux_x86.zip">HastyScribe for Linux (x86)</a> – Cross-compiled on Mac OS X Sierra (GNU GCC 4.8.1)</li> -<li><a href="https://github.com/h3rald/hastyscribe/releases/download/v1.5.0/hastyscribe_v1.5.0_linux_arm.zip">HastyScribe for Linux (ARM)</a> – Cross-compiled on Mac OS X Sierra (GNU GCC 4.8.2)</li> +<li><a href="https://github.com/h3rald/hastyscribe/releases/download/v1.6.0/hastyscribe_v1.6.0_macos_x64.zip">HastyScribe for Mac OS X (x64)</a> – Compiled on Mac OS X Sierra (LLVM CLANG 8.0.0)</li> +<li><a href="https://github.com/h3rald/hastyscribe/releases/download/v1.6.0/hastyscribe_v1.6.0_windows_x64.zip">HastyScribe for Windows (x64)</a> – Cross-compiled on Mac OS X Sierra (MinGW-w64 GCC 4.8.2)</li> +<li><a href="https://github.com/h3rald/hastyscribe/releases/download/v1.6.0/hastyscribe_v1.6.0_linux_x64.zip">HastyScribe for Linux (x64)</a> – Cross-compiled on Mac OS X Sierra (GNU GCC 4.8.1)</li> +<li><a href="https://github.com/h3rald/hastyscribe/releases/download/v1.6.0/hastyscribe_v1.6.0_linux_x86.zip">HastyScribe for Linux (x86)</a> – Cross-compiled on Mac OS X Sierra (GNU GCC 4.8.1)</li> +<li><a href="https://github.com/h3rald/hastyscribe/releases/download/v1.6.0/hastyscribe_v1.6.0_linux_arm.zip">HastyScribe for Linux (ARM)</a> – Cross-compiled on Mac OS X Sierra (GNU GCC 4.8.2)</li> </ul>@@ -4648,6 +4655,23 @@ <li>If you want to use the current date, enter <span class="kwd">% -</span> in the third line.</li>
</ul> </div> +<a name="Transclusion"></a> +<h3>Transclusion<a href="#document-top" title="Go to top"></a></h3> + +<p>When writing a long document, it is often useful to split it into many different files, to manage its contents better. HastyScribe provides basic content transclusion support through the following syntax:</p> + +<p><code>{@ my-file.md || 1 @}</code></p> + +<p>When a file is processed, the line above will cause the contents of file <span class="file">my-file.md</span> to be included in the current file, as if they were part of it. Additionally, when using content transclusion syntax, it is mandatory to specify a number between 0 and 5 to indicate the <em>offset</em> of the headings present in the transcluded file. In this example, the heading numbers of all headings present in <span class="file">my-file.md</span> will be increased by 1, so any <span class="kwd">h2</span> will become <span class="kwd">h3</span>, any <span class="kwd">h3</span> will become <span class="kwd">h4</span>, and so on.</p> + +<div class="warning"><p>Limitations</p> + +<ul> +<li>It is recommended to place all transcluded files in the same folder as the transcluding file. If a transcluded file includes any image, its relative path will be interpreted as if it was relative to the transcluding file.</li> +<li>Heading offset will only work if headings are created using <span class="kwd">#</span>s. Underline syntax for <span class="kwd">h1</span> and <span class="kwd">h2</span> is not supported.</li> +</ul> +</div> + <a name="Snippets"></a> <h3>Snippets<a href="#document-top" title="Go to top"></a></h3>@@ -4684,7 +4708,7 @@ </thead>
<tbody> <tr> <td><code>{{$timestamp}}</code> </td> -<td> 1489242640</td> +<td> 1489248321</td> </tr> <tr> <td><code>{{$date}}</code> </td>@@ -4708,19 +4732,19 @@ <td> 3/11/17</td>
</tr> <tr> <td><code>{{$short-time}}</code> </td> -<td> 15:30 PM</td> +<td> 17:05 PM</td> </tr> <tr> <td><code>{{$short-time-24}}</code> </td> -<td> 15:30</td> +<td> 17:05</td> </tr> <tr> <td><code>{{$time}}</code> </td> -<td> 15:30:40 PM</td> +<td> 17:05:21 PM</td> </tr> <tr> <td><code>{{$time-24}}</code> </td> -<td> 15:30:40</td> +<td> 17:05:21</td> </tr> <tr> <td><code>{{$day}}</code> </td>
M
hastyscribe.nim
→
hastyscribe.nim
@@ -392,7 +392,7 @@
when isMainModule: let usage = " HastyScribe v" & version & " - Self-contained Markdown Compiler" & """ - (c) 2013-2016 Fabio Cevasco + (c) 2013-2017 Fabio Cevasco Usage: hastyscribe <markdown_file_or_glob> [options]
M
hastyscribe.nimble
→
hastyscribe.nimble
@@ -1,6 +1,6 @@
[Package] name = "hastyscribe" -version = "1.5.0" +version = "1.6.0" author = "Fabio Cevasco" description = "Self-contained markdown compiler generating self-contained HTML documents" license = "MIT"