This section of the documentation will walk you through a simple project from start to finish. You will setup a website with three pages including a nested page.
The complete set of files you will generate during this example can be found
in the examples
folder on GitHub or in your node_modules/markugen/markdown/examples directory
of your project that has Markugen installed.
Additionally, all the files are provided with this documentation in the examples folder.
The next step will be to setup a folder structure for your documentation where we will put the markdown files. Begin by creating the following folder structure within your project:
Now that we have a folder structure, let's begin adding markdown files to the folders.
The first file will be created in the docs directory. Download
the following file or copy and paste the markdown into a file named
Home.md and place the file in the docs directory.
# My Home
This is the home page of my website, isn't it pretty?
## Section 1.10.33 of "de Finibus Bonorum et Malorum"
At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis
praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias
excepturi sint occaecati cupiditate non provident, similique sunt in culpa qui
officia deserunt mollitia animi, id est laborum et dolorum fuga. Et harum
quidem rerum facilis est et expedita distinctio. Nam libero tempore, cum soluta
nobis est eligendi optio cumque nihil impedit quo minus id quod maxime placeat
facere possimus, omnis voluptas assumenda est, omnis dolor repellendus.
Temporibus autem quibusdam et aut officiis debitis aut rerum necessitatibus
saepe eveniet ut et voluptates repudiandae sint et molestiae non recusandae.
Itaque earum rerum hic tenetur a sapiente delectus, ut aut reiciendis
voluptatibus maiores alias consequatur aut perferendis doloribus asperiores
repellat.
### Translation
On the other hand, we denounce with righteous indignation and dislike men who
are so beguiled and demoralized by the charms of pleasure of the moment, so
blinded by desire, that they cannot foresee the pain and trouble that are bound
to ensue; and equal blame belongs to those who fail in their duty through
weakness of will, which is the same as saying through shrinking from toil and
pain. These cases are perfectly simple and easy to distinguish. In a free hour,
when our power of choice is untrammelled and when nothing prevents our being
able to do what we like best, every pleasure is to be welcomed and every pain
avoided. But in certain circumstances and owing to the claims of duty or the
obligations of business it will frequently occur that pleasures have to be
repudiated and annoyances accepted. The wise man therefore always holds in
these matters to this principle of selection: he rejects pleasures to secure
other greater pleasures, or else he endures pains to avoid worse pains.
# Help
If you need any help with this website, please contact Falkor Clark at
[falkorclark@gmail.com](mailto:falkorclark@gmail.com) or submit an issue
on GitHub at
[github.com/falkorclark/markugen](https://github.com/falkorclark/markugen/issues).When creating subfolders on your website, you will need to provide a markdown
file at the same level as the folder with the same name if you would like the
section to have a page. For this example, we will give the subsection folder
its own page by adding a markdown file named subsection.md that we will
place in the docs folder.
Download the following file or copy and paste the markdown into a file named
subsection.md and place the file in the docs directory.
# My Website Section
This is a section of my website that provides some examples of the features
available in Markugen. The examples can be found
[here](./subsection/examples.md).
## Lorem Ipsum Passage
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
culpa qui officia deserunt mollit anim id est laborum.
## Lorem Ipsum Translation
But I must explain to you how all this mistaken idea of denouncing pleasure
and praising pain was born and I will give you a complete account of the
system, and expound the actual teachings of the great explorer of the truth,
the master-builder of human happiness. No one rejects, dislikes, or avoids
pleasure itself, because it is pleasure, but because those who do not know how
to pursue pleasure rationally encounter consequences that are extremely
painful. Nor again is there anyone who loves or pursues or desires to obtain
pain of itself, because it is pain, but because occasionally circumstances
occur in which toil and pain can procure him some great pleasure. To take a
trivial example, which of us ever undertakes laborious physical exercise,
except to obtain some advantage from it? But who has any right to find fault
with a man who chooses to enjoy a pleasure that has no annoying consequences,
or one who avoids a pain that produces no resultant pleasure?
The last page we will add is the examples page. This page will be a part of
the subsection we created; therefore, it will be placed in the subsection
folder.
Download the following file or copy and paste the markdown into a file named
examples.md and place the file in the docs/subsection directory.
# Examples
This page shows off some of the features/components available in Markugen.
## Admonitions/Callouts
Markugen provides a set of admonitions using GitHub flavored syntax. There are
five (5) types of callouts shown below:
> [!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!
## Tabs
Tabs are reactive and are custom to Markugen. When creating tabs, the result
will look like the following:
:::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.~~
:::
## Code Blocks
The following is an inline code block: `foo('hello world')`
This is a code block with hard coded text:
~~~js
// This is a code block test
function foo()
{
const bar = 'Hello World!';
console.log(bar);
}
~~~
Now that we have a set of markdown files, we can generate our website from
the files. To generate the files, create an instance of Markugen and set the
input options to the location of yours docs folder that we created above
by adding the following code somewhere in your project:
// import markugen
import Markugen from 'markugen';
// create an instance
const mark = new Markugen();
// generate the website
await mark.generate({
input: 'docs',
});Note
Markugen will output some messages to let you know its progress. If you would
like Markugen to be quiet, feel free to add quiet: true to the options and
Markugen will silence its output.
If all was successful, you should now have a set of HTML files located in a
folder called output (this is the default folder for output). Feel free to
walk through the website that was generated to get a feel for what Markugen
produces as output.
You may have noticed that the page titles are identical to the name of the
markdown file used for each page; this is what Markugen does by default, but
these titles can be customized without the need for a file rename. Additionally,
the website title is Markugen vX.X.X which is probably not what you want your
website to be titled; therefore, this title can also be customized.
Let's first customize your website's title by adding an option to Markugen's
constructor called title. We will name the website My Markugen Website by
modifying your code to look like the following:
// import markugen
import Markugen from 'markugen';
// create the instance
const mark = new Markugen();
// generate the website
mark.generate({
input: 'docs',
title: 'My Markugen Website', // customize the website title
});The next step is to customize your page titles. For this step, we will need to
create a new file with the name markugen.json and place it in the directory
of the pages we want to customize. We are going to change the title of the
subsection.md page; therefore, please download the following file or copy and
paste the text into a file called markugen.json and put it in the root docs
directory:
[
{ "name": "subsection", "title": "My Website Section" }
]Note
This file is a JSON file that allows you to add some
custom page settings. Each directory of your input will need its own
markugen.json file if you wish to customize any pages within that directory.
The JSON file has a single JSON array in it that is an array of objects. The
only required object property is the name, which must match the base name
(no extension) of the page you wish to customize. In this example, you will
see that we have provided a custom title for the subsection page called
My Website Section.
Tip
The page order that is generated is based on alphabetical order of your
markdown input files. If you would like to change the order of the pages, you
can provide a custom order in your markugen.json file by simply ordering
the pages in your array in the order you would like.
Now that we have customized our titles, we can go ahead and generate the website
again by executing the file that contains our Markugen instance.
This example walked you through the generation of a website from a set of 3 markdown files and a subfolder to provide a section on your website. Some of the features that you should be able to do now are:
There are many more features available to you, so please take a look at the Features Section section for more advanced topics.