The following sections show examples of components that can be used within the markdown files passed to Markugen.
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:
> [!NOTE]
> This is a note.
> [!TIP]
> This is a tip.
> [!IMPORTANT]
> This is important.
> [!CAUTION]
> This is a caution alert!
> [!WARNING]
> This is a warning alert!Note
This is a note.
Tip
This is a tip.
Important
This is important.
Caution
This is a caution alert!
Warning
This is a warning alert!
Tables use the basic markdown syntax with alignment support. The following markdown will result in the table that follows:
| Left Column | Right Column | Centered Column |
|:----------------|----------------:|-----------------|
| Foo | Bar | Centered |
| Foo | Bar | Centered |
| Foo | Bar | Centered |
| Foo | Bar | Centered || Left Column | Right Column | Centered Column |
|---|---|---|
| Foo | Bar | Centered |
| Foo | Bar | Centered |
| Foo | Bar | Centered |
| Foo | Bar | Centered |
Tabs are reactive and are custom to Markugen. The following markdown syntax will result in the tabs that follow:
:::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.
*Italicize this line please.*
**Bold this line please.**
~~Strike through this line please.~~
:::This tab has some text on different lines.
Like this line and the previous.
This tab has only one line.
This tab has some formatting in it.
Italicize this line please.
Bold this line please.
Strike through this line please.
This tab has some text on different lines.
Like this line and the previous.
This tab has only one line.
This tab has some formatting in it.
Italicize this line please.
Bold this line please.
Strike through this line please.
The following is an inline code block: foo('hello world')
This is a code block with hard coded text:
// This is a code block test
function foo()
{
const bar = 'Hello World!';
console.log(bar);
}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.
The markugen.import command will import a text file into the code block. The
following is an example of the index.md markdown file used to generate
the home page of this documentation.
markugen.import ../index.md# Markugen
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.
## Inspiration
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:
* [Nextra](https://nextra.site/)
* [VuePress](https://vuepress.vuejs.org/)
* [Remark](https://github.com/remarkjs/remark) with [Rehype](https://github.com/rehypejs/rehype)
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
[pkg](https://www.npmjs.com/package/pkg)
and [nexe](https://www.npmjs.com/package/nexe). Therefore, I chose to begin
using [marked](https://marked.js.org/) 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:
## Major Features
* Markdown to HTML
* Markdown to PDF
* Website generation
* Static HTML generation (no need for a server)
* Fully typed with [TypeScript](https://www.typescriptlang.org/)
* Reactive website sitemap and Table of Contents
* [Markdown Components](./Features/Components.md):
* Admonitions/Callouts (GitHub flavored)
* Tabs
* Tables
* Dynamic Code Blocks
* Dark and light themes
## Issues and Feature Requests
This NodeJS package was developed by Falkor Clark. Please contact Falkor at
[falkorclark@gmail.com](mailto:falkorclark@gmail.com) or submit an issue
on [GitHub](https://github.com) at
[github.com/falkorclark/markugen](https://github.com/falkorclark/markugen/issues).The markugen.exec command will execute a shell command and populate the code
block with the output from the execution. The following example executes the
echo command with a string:
markugen.exec echo "Hello World!"Hello World!