-
Notifications
You must be signed in to change notification settings - Fork 0
Syntax Extensions
To use additional elearn.js features or add meta information or scripts to the HTML Head you can use the following syntax.
Sections are automatically created at headings. These sections are used by
elearn.js to create pages. This can be changed with conversion settings.
When using markdown-elearnjs directly check Conversion,
otherwise check the Wiki of the package you use for a description of available
settings.
By default headings up to ### Heading 3
will start a new section with the name set to the headings text.
If you only want a specific heading to not start a new section, insert
<!--no-section--> into the headings text like this:
## Example Heading <!--no-section-->
If you disable this option or want a new section at a specific point, you can insert
|||SECTION_NAME|||
This way the html will contain a surrounding <section name="SECTION_NAME">.
There are also syntax extensions for subsections and subsubsections
||||SUB_SECTION||||
|||||SUB_SUB_SECTION|||||
If you want to use | as a character within the sections name, you have to
escape it with an \. So | becomes \| like this
|||Example \| Section 1|||. Using normal markdown headings with autogenerated
sections like ## Example | Section 1 is still possible without further
escaping. Also \ chars always have to be escaped when you want to write them
as a character in a text. See the
Usage of backslashes section in Useful Hints
for further information.
Notice: You should always insert the first section before everything else (besides not displayed elements like the meta information or imprint below). Other displayed elements before the first section will otherwise always be visible.
Elearn.js has support for an automatically created content overview based on sections. You can insert this overview by adding the following block
<div id="content-overview" class="kachel">
<!-- Keep this empty. This will be automatically generated. -->
</div>
This will create a basic list overview. If you want to use a "block" theme, you
can add class="kachel" to the <div> (<div id="content-overview" class="kachel">).
With this theme checkmarks will be displayed for all sections visited already.
You can add hide-read to the class to deactivate these checkmarks
(<div id="content-overview" class="kachel hide-read">).
If you want to hide sections in this overview e.g. the content overview section
itself you can add a comment <!--hide-in-overview--> like this
## Content Overview <!--hide-in-overview-->
|||Content Overview||| <!--hide-in-overview-->
markdown-elearnjs supports the description feature of elearn.js.
This means that it is possible to add a desc attribute to the <section> to
write a short description, which is displayed in the content overview (for the
kachel style only).
To do so you can simply add a comment to the heading or section like before:
## My section <!--desc This section is very important-->
|||My section||| <!--desc This section is very important-->
It is necessary to write <!--desc including the trailing space. You can
close it without an additional space there.
You can only write this descriptions in one line. Line breaks are not
supported. If you want a displayed line break in the description you can write
<br /> to do so. Also it is allowed to use markdown syntax.
Example:
## My section <!--desc Has a _description_ with <br /> line breaks.-->
If you have a block in your Markdown code you do not want to be converted you
have the option to wrap it in a <div> or <p>. But if you do not want to
do that, you can also deactivate Markdown conversion for this block using
the comments <!--markdown-disable--> and <!--markdown-enable--> (since v1.7.2):
<!--markdown-disable-->
This is a block in which no markdown should be processed.
It can contain $formulas__with$ anything $markdown *would__convert*$.
<!--markdown-enable-->Converts to:
This is a block in which no markdown should be processed.
It can contain $formulas__with$ anything $markdown *would__convert*$.Please note the missing <p>. This might lead to unexpected results.
Otherwise you can wrap the block in HTML. This might not work with inline code. The following block will not be changed in any way.
<p>
This is a block in which no markdown should be processed.
It can contain $formulas__with$ anything $markdown *would__convert*$.
</p>Html comments are by default kept in the output. So whenever you write a comment it can still be found in the Html output. You can set an option to remove all comments from the output (check the Conversion Wiki). This can be handy if you only want to use comments for yourself while writing the document, but do not want anyone to see those in the result.
There is also a syntax for always hidden comments. Those will be removed from the output even if you deactivate comment removal.
Just write your comment like the following example
<!--hide This is a hidden comment-->
You need to start your comment with <!--hide followed by at least one space
and finish it with --> to be removed in the conversion process.
The following block has to be added to the markdown file (preferably at the top) to add meta information to the generated HTML-File.
---
Title: elearn.js Template
Author: Name Author
Description: Enter Descriptions
Keywords: Key, Words
Custom: "<script type=\"text/x-mathjax-config\">
MathJax.Hub.Config({
extensions: [\"tex2jax.js\"],
jax: [\"input/TeX\", \"output/HTML-CSS\"],
tex2jax: {
inlineMath: [ ['$','$'], [\"\\(\",\"\\)\"] ],
displayMath: [ ['$$','$$'], [\"\\[\",\"\\]\"] ],
processEscapes: true
},
\"HTML-CSS\": { availableFonts: [\"TeX\"] }
});
</script>
<script type=\"text/javascript\"
src=\"https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js\"></script>"
---
This will basically add <meta> elements to the HTML's Head.
For example Author: Name Author, where Author might be called Key and
Name Author Value, will be converted to
<meta name="author" content="Name Author"/>. There are only two exceptions to
this rule.
-
Titlewill convert to a<title>element. -
Customwill add the value without any conversion to the Head. In this example the MathJax Script is loaded and initiated.
If you want to write a value over multiple lines you can surround it with '
or " otherwise it will only get interpreted as single line value. The chosen
wrapper has to be escaped within the value. This can also be seen in the example
above. Another example: Title: An "Example" with quotes is equal to
Title: "An \"Example\" with quotes" and Title: 'An "Example" with quotes'.
The --- wrapping the block is necessary if you include this block.
All Key-Value pairs have to be within these --- lines. If you want to be sure
the block will not be converted to anything else by other converters you can
also use the alternative syntax:
<!--meta
Title: elearn.js Template
Author: ...
-->
This way you are save to use this even when working with other converters. But
you cannot use --> in the block and the editor will most likely not highlight
the syntax.
It is recommended to not indent the attribute keys (e.g. "Title") in the meta block. This might lead to unwanted behavior, although it should be supported.
All fields are optional as well as the block itself.
In the HTML version's menu of an elearn.js document is an imprint. To add your imprint information you have to add the following block to the markdown code.
<!--imprint
YOUR CODE HERE
-->
Within this block either markdown or html is allowed. Up to version 0.3.2 you may not indent the imprint code because indented code will be converted to a code block. Following versions support one indention up to four spaces.
This block is optional but it is recommended to insert this block at the top of your markdown file. This block should not be converted in other markdown converters due to its html comment style. This way you are save to use this even when working with other converters. But of course other converters will not generate any output based on this block. There are two alternatives to this syntax:
```imprint
YOUR CODE HERE
```
and
~~~imprint
YOUR CODE HERE
~~~