Security News
tea.xyz Spam Plagues npm and RubyGems Package Registries
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
mdtk
Advanced tools
A markdown toolkit to simplify the creation of maintainable, composable documents.
Readme
A Markdown processor that features carefully designed syntax extensions to simplify the creation and maintenance of composable documents.
It supports:
A complete document is built using a packager, among which revealjs
and typora
.
NodeJS 8.12 is tested. It is not built for the browser and support for this is not planned for now.
npm install -g mdtk
Show inline documentation:
mdtk --help
Simple example:
mdtk in.md > out.html
# Or using pipes
mdtk < in.md > out.html
Bootstrap a new project:
mdtk bootstrap my-mdtk-project
Render the project:
mdtk --config my-mdtk-project/mdtk.yaml
Most projects will eventually prefer setting all parameters in the configuration file:
packager: revealjs
input: content/index.md
output: output/index.html
mdtk --config config.yaml
mdtk
supports a number of invocation methods, please refer to mdtk --help
.
mdtk
can be configured via the command line or a configuration file (referenced
using --config
).
The structure of the configuration file mirrors the command line arguments nearly exactly.
It can be formatted as JSON, YAML or HCL.
Any option defined on the command line wll override the value defined in the configuration file, even if the option is repeatable.
You can view the configuration being applied by setting the environment variable
DEBUG=*
.
mdtk
implements CommonMark (via markdown-it), with some extensions.
mdtk
passes through a template engine to interpolate variables.
Variables can be provided in different ways:
--vars
)mdtk render --vars.presenter.name John <<EOF
My name is {{ presenter.name }}
EOF
--varfiles
)cat <<EOF > vars.json
{
"presenter": {
"name": "John"
}
}
EOF
mdtk render --varfiles vars.json <<EOF
My name is {{ presenter.name }}
EOF
Just like the configuration file, varfiles can be provided as JSON, YAML or HCL.
--envfiles
)cat <<EOF > envfile
PRESENTER_NAME=John
EOF
mdtk render --envfiles envfile <<EOF
My name is {{ PRESENTER_NAME }}
EOF
Currently substitutions in variable values are not supported. The following won't work:
PORT=80 URL=http://localhost:$PORT
Instead, use:
PORT=80 URL=http://localhost:80
vars:
foo:
baz: bar
biz: laz
varfiles:
- vars.json
at-rules
are a series of syntax extension that follow the same generic format:
@rule-name(arg1, ...argN)
They can span multiple lines. If passing a value containing a comma or a closing parenthesis is required, the value may be enclosed in double quotes ("
). Alternatively, any character may be quoted using a "\".
@meta(name, content)
Inserts a <meta>
tag with the specified name and content.
@include(path/to/file.md)
Inserts the contents of the given file in place. The path can be absolute or relative.
If it is relative, it will be resolved relative to the including fragment, or to the
--include
arguments. The path can include interpolated variables, e.g. @include(path/to/{{ master }})
.
@code(path/to/code.js)
@code(path/to/code.js, js)
Similar to @include
, but translates to a highlighted code block in the presentation, using the contents
of the given file.
The second argument should be the highlight.js language. If omitted, the file is not highlighted.
@css(path/to/file.css)
Inserts a <link rel="stylesheet">
tag. The CSS file is resolved using exactly the same
logic as described in @include
.
- If the CSS file references external assets using
url(path/to/something)
, the assets will be resolved
@js(path/to/file.js)
Inserts a <script>
tag. The JS file is resolved using exactly the same logic as described
in @include
.
@section(name, value)
Sets an HTML attribute on the current section
tag. This only makes sense when using the
nesting syntax.
mdtk
replaces the classic hr
rules with nesting logic.
The following markdown:
Section 1
---
Section 2.a
===
Section 2.b.a
|||
Section 2.b.b
---
Section 3
Produces the following HTML:
<section>
Section 1
</section>
<section>
<section>
Section 2.a
</section>
<section>
<section>
Section 2.b.a
</section>
<section>
Section 2.b.b
</section>
</section>
</section>
<section>
Section 3
</section>
Implicit nesting is very useful for expressing document flow, but layout requirements are best served by an explicit approach.
+columns
- eenie
- meenie
- ...
-columns
Will render to:
<div class="columns">
<ul>
<li>eenie</li>
<li>meenie</li>
<li>...</li>
</ul>
</div>
- Containers can be nested
- Indenting the contents of a container is not supported
Syntax highlighting is performed using highlight.js
.
Generating plantuml diagrams is supported using markdown-it-plantuml
.
@startuml
...
@enduml
You can embed vega
/vega-lite
visualizations into your documents:
@startvega
...
@endvega
@startvegalite
...
@endvegalite
If your spec
references a data url, mdtk
will resolve it using the same
rules as the @include
at-rule.
Local data files will NOT be copied to the output directory (for now), because rendering is done offline and the SVG output is directly embedded in the final HTML document. I can see two good reasons for including the data in the output directory like all other assets:
- to support online rendering (with
vega
signals etc...)- to support adding a "Download data" link to the SVG caption
Speaker Notes can be defined using explicit nesting and notes
class name. Example use:
+notes
Speaker notes go here. You can use markdown syntax:
* item 1
* item 2
-notes
You can add [[toc]]
where you want the table of contents to be added in your markdown. Example use:
# Heading
[[toc]]
## Sub heading 1
Some nice text
## Sub heading 2
Some even nicer text
Table of Contents works with any packager, however you may want to use it with
typora
in linear documents.
Experimental video support is provided via markdown-it-html5-media.
Videos use the image syntax. The player controls are disabled and autoplay is off, there is custom code within the revealjs packager to start playback when a fragment containing a video is shown.
+fragment
![descriptive text](video.mp4)
-fragment
mdtk
performs two main tasks:
Currently mdtk
supports three packagers:
null
(default)mdtk
will not do any packaging and will write the HTML generated from the markdown without
wrapping it in a document template.
revealjs
: for presentationsmdtk
will package the generated HTML into a RevealJS presentation.
typora
: to generate linear documentsmdtk
will package the generated HTML into a linear document suitable for handbooks. This packager
is called typora
because it is inspired by the tool with the same name and steals the CSS from its
themes, this does not imply compatibility with typora markdown.
More details will be added as this feature stabilizes.
../
-style components--serve
for a nice live-reload experience@css
: resolve @import
@xxx
: better argument parsing (allow commas)tests
: fix the tests and improve coveragepackager
: make the highlight.js theme configurableext
: local plantuml serverext
: vega & vega-litedocumentation
: create guides for authoring different doc typesdocumentation
: improve the theme of the exampledocumentation
: include examples for each packagerAnd many more things.
npm install
error output when building canvas
modulenode-gyp
expects python 2. If python 3 is your default version, you can run:
npm install --python=python2.7 mdtk
FAQs
A markdown toolkit to simplify the creation of maintainable, composable documents.
The npm package mdtk receives a total of 16 weekly downloads. As such, mdtk popularity was classified as not popular.
We found that mdtk demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.