markugen
Version:
Markdown to HTML/PDF static site generation tool
328 lines (303 loc) • 20.4 kB
HTML
<html lang="en">
<head>
<meta charset="utf-8">
<meta content="width=device-width, initial-scale=1" name="viewport">
<title>Components</title>
<link rel="stylesheet" href="../markugen.css">
</head>
<body>
<h1 id="components">Components</h1>
<p>The following sections show examples of components that can be used within
the markdown files passed to Markugen.</p>
<h2 id="admonitionscallouts">Admonitions/Callouts</h2>
<p>Admonitions or Callouts follow GitHub flavored syntax. There are five (5) types
of callouts shown in the code below that results in the callouts that follow:</p>
<h5 id="markdown">Markdown</h5>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.md</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-18', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-18" class="hljs language-md"><span class="hljs-quote">> [!NOTE]</span>
<span class="hljs-quote">> This is a note.</span>
<span class="hljs-quote">> [!TIP]</span>
<span class="hljs-quote">> This is a tip.</span>
<span class="hljs-quote">> [!IMPORTANT]</span>
<span class="hljs-quote">> This is important.</span>
<span class="hljs-quote">> [!CAUTION]</span>
<span class="hljs-quote">> This is a caution alert!</span>
<span class="hljs-quote">> [!WARNING]</span>
<span class="hljs-quote">> This is a warning alert!</span></code></pre>
</div><h5 id="result">Result</h5>
<div class="markdown-alert markdown-alert-note">
<p class="markdown-alert-title"><svg class="octicon octicon-info mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>Note</p>
<p>This is a note.</p>
</div>
<div class="markdown-alert markdown-alert-tip">
<p class="markdown-alert-title"><svg class="octicon octicon-light-bulb mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z"></path></svg>Tip</p>
<p>This is a tip.</p>
</div>
<div class="markdown-alert markdown-alert-important">
<p class="markdown-alert-title"><svg class="octicon octicon-report mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>Important</p>
<p>This is important.</p>
</div>
<div class="markdown-alert markdown-alert-caution">
<p class="markdown-alert-title"><svg class="octicon octicon-stop mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>Caution</p>
<p>This is a caution alert!</p>
</div>
<div class="markdown-alert markdown-alert-warning">
<p class="markdown-alert-title"><svg class="octicon octicon-alert mr-2" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>Warning</p>
<p>This is a warning alert!</p>
</div>
<h2 id="tables">Tables</h2>
<p>Tables use the basic markdown syntax with alignment support. The following
markdown will result in the table that follows:</p>
<h5 id="markdown-1">Markdown</h5>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.md</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-19', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-19" class="hljs language-md">| Left Column | Right Column | Centered Column |
|:----------------|----------------:|-----------------|
| Foo | Bar | Centered |
| Foo | Bar | Centered |
| Foo | Bar | Centered |
| Foo | Bar | Centered |</code></pre>
</div><h5 id="result-1">Result</h5>
<table>
<thead>
<tr>
<th align="left">Left Column</th>
<th align="right">Right Column</th>
<th>Centered Column</th>
</tr>
</thead>
<tbody><tr>
<td align="left">Foo</td>
<td align="right">Bar</td>
<td>Centered</td>
</tr>
<tr>
<td align="left">Foo</td>
<td align="right">Bar</td>
<td>Centered</td>
</tr>
<tr>
<td align="left">Foo</td>
<td align="right">Bar</td>
<td>Centered</td>
</tr>
<tr>
<td align="left">Foo</td>
<td align="right">Bar</td>
<td>Centered</td>
</tr>
</tbody></table>
<h2 id="tabs">Tabs</h2>
<p>Tabs are reactive and are custom to Markugen. The following markdown syntax
will result in the tabs that follow:</p>
<h5 id="markdown-2">Markdown</h5>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.md</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-20', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-20" class="hljs language-md">:::tabs
::tab[Tab 1]
This tab has some text on different lines.
Like this line and the previous.
::tab[Tab 2]
This tab has only one line.
::tab[Tab 3]
This tab has some formatting in it.
<span class="hljs-emphasis">*Italicize this line please.*</span>
<span class="hljs-strong">**Bold this line please.**</span>
~~Strike through this line please.~~
:::</code></pre>
</div><h5 id="result-2">Result</h5>
<div class="markugen-tabs-container markugen-not-printable">
<div class="markugen-tabs-labels">
<div name="tab-1" class="markugen-tab-label active">Tab 1</div>
<div name="tab-2" class="markugen-tab-label">Tab 2</div>
<div name="tab-3" class="markugen-tab-label">Tab 3</div>
</div>
<div class="markugen-tabs">
<div name="tab-1" class="markugen-tab">
<p>This tab has some text on different lines.</p>
<p>Like this line and the previous.</p>
</div>
<div name="tab-2" class="markugen-tab markugen-hidden">
<p>This tab has only one line.</p>
</div>
<div name="tab-3" class="markugen-tab markugen-hidden">
<p>This tab has some formatting in it.
<em>Italicize this line please.</em>
<strong>Bold this line please.</strong>
<del>Strike through this line please.</del></p>
</div>
</div>
</div>
<div name="tab-1" class="markugen-tabs-container markugen-printable">
<div name="tab-1" class="markugen-tab-label">Tab 1</div>
<div name="tab-1" class="markugen-tab">
<p>This tab has some text on different lines.</p>
<p>Like this line and the previous.</p>
</div>
</div>
<div name="tab-2" class="markugen-tabs-container markugen-printable">
<div name="tab-2" class="markugen-tab-label">Tab 2</div>
<div name="tab-2" class="markugen-tab">
<p>This tab has only one line.</p>
</div>
</div>
<div name="tab-3" class="markugen-tabs-container markugen-printable">
<div name="tab-3" class="markugen-tab-label">Tab 3</div>
<div name="tab-3" class="markugen-tab">
<p>This tab has some formatting in it.
<em>Italicize this line please.</em>
<strong>Bold this line please.</strong>
<del>Strike through this line please.</del></p>
</div>
</div>
<h2 id="code-blocks">Code Blocks</h2>
<p>The following is an inline code block: <code>foo('hello world')</code></p>
<p>This is a code block with hard coded text:</p>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.js</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-21', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-21" class="hljs language-js"><span class="hljs-comment">// This is a code block test</span>
<span class="hljs-keyword">function</span> <span class="hljs-title function_">foo</span>(<span class="hljs-params"></span>)
{
<span class="hljs-keyword">const</span> bar = <span class="hljs-string">'Hello World!'</span>;
<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(bar);
}</code></pre>
</div><h3 id="commands">Commands</h3>
<p>Commands are options that Markugen allows you to execute within code blocks
in your markdown file. Depending on the command, Markugen will populate the code
block with data from executing that command.</p>
<h4 id="markugenimport">markugen.import</h4>
<p>The <code>markugen.import</code> command will import a text file into the code block. The
following is an example of the <code>index.md</code> markdown file used to generate
<a class="markugen-md-link" href="../index.html">the home page of this documentation</a>.</p>
<h5 id="markdown-3">Markdown</h5>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.sh</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-22', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-22" class="hljs language-sh">markugen.import ../index.md</code></pre>
</div><h5 id="result-3">Result</h5>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">index.md</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-23', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
<div title="Save to index.md" class="markugen-code-save" onclick="markugen.saveToFile('copy-save-23', 'index.md', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M840-680v480q0 33-23.5 56.5T760-120H200q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h480l160 160Zm-80 34L646-760H200v560h560v-446ZM480-240q50 0 85-35t35-85q0-50-35-85t-85-35q-50 0-85 35t-35 85q0 50 35 85t85 35ZM240-560h360v-160H240v160Zm-40-86v446-560 114Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-23" class="hljs language-md"><span class="hljs-section"># Markugen</span>
Markugen was designed to make it easier for developers and non-developers to
create an entire website from a set of Markdown files. It is designed with
brevity, clarity, and ease-of-use in mind. Additionally, the pages produced
are static pages allowing for viewing without the need for a server.
The documentation you are viewing right now was generated using Markugen.
<span class="hljs-section">## Inspiration</span>
Before developing this package, I used many other packages to try and accomplish
developing a set of HTML documentation from markdown files. Some of the packages
I first used were the following:
<span class="hljs-bullet">*</span> [<span class="hljs-string">Nextra</span>](<span class="hljs-link">https://nextra.site/</span>)
<span class="hljs-bullet">*</span> [<span class="hljs-string">VuePress</span>](<span class="hljs-link">https://vuepress.vuejs.org/</span>)
<span class="hljs-bullet">*</span> [<span class="hljs-string">Remark</span>](<span class="hljs-link">https://github.com/remarkjs/remark</span>) with [<span class="hljs-string">Rehype</span>](<span class="hljs-link">https://github.com/rehypejs/rehype</span>)
Nextra and VuePress both generate beautiful documentation, but depend on a server
to serve the resulting website. Remark and rehype were great options for
generating static HTML pages from markdown files; however, they are ESM only
modules and that causes problems with packagers like
[<span class="hljs-string">pkg</span>](<span class="hljs-link">https://www.npmjs.com/package/pkg</span>)
and [<span class="hljs-string">nexe</span>](<span class="hljs-link">https://www.npmjs.com/package/nexe</span>). Therefore, I chose to begin
using [<span class="hljs-string">marked</span>](<span class="hljs-link">https://marked.js.org/</span>) for its CommonJS support and found this
and the many extensions to it to be the perfect starting point.
Marked does a great job of parsing markdown into HTML, but it is designed to
handle a single markdown string as input. Therefore, I have developed this
package to generate an entire website with navigation from a set of markdown
files. The resulting website does not require a server to host the pages and
Markugen gives you the option to embed all required scripts and styles into
each page that is generated to allow each page to be viewed independently. Some
of the major features are listed below:
<span class="hljs-section">## Major Features</span>
<span class="hljs-bullet">*</span> Markdown to HTML
<span class="hljs-bullet">*</span> Markdown to PDF
<span class="hljs-bullet">*</span> Website generation
<span class="hljs-bullet">*</span> Static HTML generation (no need for a server)
<span class="hljs-bullet">*</span> Fully typed with [<span class="hljs-string">TypeScript</span>](<span class="hljs-link">https://www.typescriptlang.org/</span>)
<span class="hljs-bullet">*</span> Reactive website sitemap and Table of Contents
<span class="hljs-bullet">*</span> [<span class="hljs-string">Markdown Components</span>](<span class="hljs-link">./Features/Components.md</span>):
<span class="hljs-bullet"> *</span> Admonitions/Callouts (GitHub flavored)
<span class="hljs-bullet"> *</span> Tabs
<span class="hljs-bullet"> *</span> Tables
<span class="hljs-bullet"> *</span> Dynamic Code Blocks
<span class="hljs-bullet">*</span> Dark and light themes
<span class="hljs-section">## Issues and Feature Requests</span>
This NodeJS package was developed by Falkor Clark. Please contact Falkor at
[<span class="hljs-string">falkorclark@gmail.com</span>](<span class="hljs-link">mailto:falkorclark@gmail.com</span>) or submit an issue
on [<span class="hljs-string">GitHub</span>](<span class="hljs-link">https://github.com</span>) at
[<span class="hljs-string">github.com/falkorclark/markugen</span>](<span class="hljs-link">https://github.com/falkorclark/markugen/issues</span>).</code></pre>
</div><h4 id="markugenexec">markugen.exec</h4>
<p>The <code>markugen.exec</code> command will execute a shell command and populate the code
block with the output from the execution. The following example executes the
<code>echo</code> command with a string:</p>
<h5 id="markdown-4">Markdown</h5>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.sh</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-24', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-24" class="hljs language-sh">markugen.exec <span class="hljs-built_in">echo</span> <span class="hljs-string">"Hello World!"</span></code></pre>
</div><h5 id="result-4">Result</h5>
<div class="markugen-code">
<div class="markugen-code-toolbar">
<div class="markugen-code-title">.txt</div>
<div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-25', this)">
<svg height="24px" viewBox="0 -960 960 960" width="24px" fill="var(--markugen-color)">
<path d="M200-120q-33 0-56.5-23.5T120-200v-560q0-33 23.5-56.5T200-840h167q11-35 43-57.5t70-22.5q40 0 71.5 22.5T594-840h166q33 0 56.5 23.5T840-760v560q0 33-23.5 56.5T760-120H200Zm0-80h560v-560h-80v120H280v-120h-80v560Zm280-560q17 0 28.5-11.5T520-800q0-17-11.5-28.5T480-840q-17 0-28.5 11.5T440-800q0 17 11.5 28.5T480-760Z"/>
</svg>
</div>
</div>
<pre class="markugen-code-content"><code id="copy-save-25" class="hljs language-txt">Hello World!</code></pre>
</div>
<script src="../markugen.js"></script>
</body>
</html>