markugen

<!doctype html> <html lang="en"> <head> <meta charset="utf-8"> <meta content="width=device-width, initial-scale=1" name="viewport"> <title>Example</title> <link rel="stylesheet" href="../markugen.css"> </head> <body> <h1 id="getting-started">Getting Started</h1> <p>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.</p> <p>The complete set of files you will generate during this example can be found in the <a target="_blank" href="https://github.com/falkorclark/markugen/tree/main/markdown/examples">examples</a> folder on GitHub or in your <code>node_modules/markugen/markdown/examples</code> directory of your project that has Markugen installed.</p> <p>Additionally, all the files are provided with this documentation in the <a href="../examples">examples</a> folder.</p> <h2 id="create-folder-structure">Create Folder Structure</h2> <p>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:</p> <ul> <li>docs<ul> <li>subsection</li> </ul> </li> </ul> <h2 id="create-markdown-files">Create Markdown Files</h2> <p>Now that we have a folder structure, let's begin adding markdown files to the folders. </p> <h3 id="home-page">Home Page</h3> <p>The first file will be created in the <code>docs</code> directory. Download the following file or copy and paste the markdown into a file named <code>Home.md</code> and place the file in the <code>docs</code> directory.</p> <div class="markugen-code"> <div class="markugen-code-toolbar"> <div class="markugen-code-title">Home.md</div> <div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-3', 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 Home.md" class="markugen-code-save" onclick="markugen.saveToFile('copy-save-3', 'Home.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-3" class="hljs language-md"><span class="hljs-section"># My Home</span> This is the home page of my website, isn't it pretty? <span class="hljs-section">## Section 1.10.33 of "de Finibus Bonorum et Malorum"</span> 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. <span class="hljs-section">### Translation</span> 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. <span class="hljs-section"># Help</span> If you need any help with this website, please contact Falkor Clark at [<span class="hljs-string">falkorclark@gmail.com</span>](<span class="hljs-link">mailto:falkorclark@gmail.com</span>) or submit an issue on GitHub at [<span class="hljs-string">github.com/falkorclark/markugen</span>](<span class="hljs-link">https://github.com/falkorclark/markugen/issues</span>).</code></pre> </div><h3 id="subsection-page">Subsection Page</h3> <p>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 <code>subsection</code> folder its own page by adding a markdown file named <code>subsection.md</code> that we will place in the <code>docs</code> folder. </p> <p>Download the following file or copy and paste the markdown into a file named <code>subsection.md</code> and place the file in the <code>docs</code> directory.</p> <div class="markugen-code"> <div class="markugen-code-toolbar"> <div class="markugen-code-title">subsection.md</div> <div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-4', 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 subsection.md" class="markugen-code-save" onclick="markugen.saveToFile('copy-save-4', 'subsection.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-4" class="hljs language-md"><span class="hljs-section"># My Website Section</span> This is a section of my website that provides some examples of the features available in Markugen. The examples can be found [<span class="hljs-string">here</span>](<span class="hljs-link">./subsection/examples.md</span>). <span class="hljs-section">## Lorem Ipsum Passage</span> 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. <span class="hljs-section">## Lorem Ipsum Translation</span> 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? </code></pre> </div><h3 id="examples-page">Examples Page</h3> <p>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 <code>subsection</code> folder.</p> <p>Download the following file or copy and paste the markdown into a file named <code>examples.md</code> and place the file in the <code>docs/subsection</code> directory.</p> <div class="markugen-code"> <div class="markugen-code-toolbar"> <div class="markugen-code-title">examples.md</div> <div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-5', 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 examples.md" class="markugen-code-save" onclick="markugen.saveToFile('copy-save-5', 'examples.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-5" class="hljs language-md"><span class="hljs-section"># Examples</span> This page shows off some of the features/components available in Markugen. <span class="hljs-section">## Admonitions/Callouts</span> Markugen provides a set of admonitions using GitHub flavored syntax. There are five (5) types of callouts shown below: <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> <span class="hljs-section">## Tabs</span> 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. <span class="hljs-emphasis">*Italicize this line please.*</span> <span class="hljs-strong">**Bold this line please.**</span> ~~Strike through this line please.~~ ::: <span class="hljs-section">## Code Blocks</span> The following is an inline code block: <span class="hljs-code">`foo('hello world')`</span> This is a code block with hard coded text: <span class="hljs-code">~~~js // This is a code block test function foo() { const bar = 'Hello World!'; console.log(bar); } ~~~</span> </code></pre> </div><h2 id="generate-website">Generate Website</h2> <p>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 <code>input</code> options to the location of yours <code>docs</code> folder that we created above by adding the following code somewhere in your project:</p> <div class="markugen-code"> <div class="markugen-code-toolbar"> <div class="markugen-code-title">.ts</div> <div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-6', 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-6" class="hljs language-ts"><span class="hljs-comment">// import markugen</span> <span class="hljs-keyword">import</span> <span class="hljs-title class_">Markugen</span> <span class="hljs-keyword">from</span> <span class="hljs-string">'markugen'</span>; <span class="hljs-comment">// create an instance</span> <span class="hljs-keyword">const</span> mark = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Markugen</span>(); <span class="hljs-comment">// generate the website</span> <span class="hljs-keyword">await</span> mark.<span class="hljs-title function_">generate</span>({ <span class="hljs-attr">input</span>: <span class="hljs-string">'docs'</span>, });</code></pre> </div><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>Markugen will output some messages to let you know its progress. If you would like Markugen to be quiet, feel free to add <code>quiet: true</code> to the options and Markugen will silence its output.</p> </div> <p>If all was successful, you should now have a set of HTML files located in a folder called <code>output</code> (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.</p> <h2 id="customize-your-titles">Customize Your Titles</h2> <p>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 <code>Markugen vX.X.X</code> which is probably not what you want your website to be titled; therefore, this title can also be customized.</p> <h3 id="custom-website-title">Custom Website Title</h3> <p>Let's first customize your website's title by adding an option to Markugen's constructor called <code>title</code>. We will name the website <code>My Markugen Website</code> by modifying your code to look like the following:</p> <div class="markugen-code"> <div class="markugen-code-toolbar"> <div class="markugen-code-title">.ts</div> <div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-7', 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-7" class="hljs language-ts"><span class="hljs-comment">// import markugen</span> <span class="hljs-keyword">import</span> <span class="hljs-title class_">Markugen</span> <span class="hljs-keyword">from</span> <span class="hljs-string">'markugen'</span>; <span class="hljs-comment">// create the instance</span> <span class="hljs-keyword">const</span> mark = <span class="hljs-keyword">new</span> <span class="hljs-title class_">Markugen</span>(); <span class="hljs-comment">// generate the website</span> mark.<span class="hljs-title function_">generate</span>({ <span class="hljs-attr">input</span>: <span class="hljs-string">'docs'</span>, <span class="hljs-attr">title</span>: <span class="hljs-string">'My Markugen Website'</span>, <span class="hljs-comment">// customize the website title</span> });</code></pre> </div><h3 id="custom-page-title">Custom Page Title</h3> <p>The next step is to customize your page titles. For this step, we will need to create a new file with the name <code>markugen.json</code> and place it in the directory of the pages we want to customize. We are going to change the title of the <code>subsection.md</code> page; therefore, please download the following file or copy and paste the text into a file called <code>markugen.json</code> and put it in the root <code>docs</code> directory:</p> <div class="markugen-code"> <div class="markugen-code-toolbar"> <div class="markugen-code-title">markugen.json</div> <div title="Copy to Clipboard" class="markugen-code-copy" onclick="markugen.copyToClipboard('copy-save-8', 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 markugen.json" class="markugen-code-save" onclick="markugen.saveToFile('copy-save-8', 'markugen.json', 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-8" class="hljs language-json"><span class="hljs-punctuation">[</span> <span class="hljs-punctuation">{</span> <span class="hljs-attr">"name"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"subsection"</span><span class="hljs-punctuation">,</span> <span class="hljs-attr">"title"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"My Website Section"</span> <span class="hljs-punctuation">}</span> <span class="hljs-punctuation">]</span></code></pre> </div><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 file is a <a target="_blank" href="https://www.json.org">JSON</a> file that allows you to add some custom page settings. Each directory of your input will need its own <code>markugen.json</code> file if you wish to customize any pages within that directory.</p> </div> <p>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 <code>subsection</code> page called <code>My Website Section</code>.</p> <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>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 <code>markugen.json</code> file by simply ordering the pages in your array in the order you would like.</p> </div> <h2 id="generate-website-with-custom-titles">Generate Website with Custom Titles</h2> <p>Now that we have customized our titles, we can go ahead and generate the website again by executing the file that contains our <code>Markugen</code> instance.</p> <h1 id="summary">Summary</h1> <p>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:</p> <ul> <li>Generate a website from markdown files</li> <li>Customize the website's title</li> <li>Customize each page's title</li> </ul> <p>There are many more features available to you, so please take a look at the <a class="markugen-md-link" href="../Features.html">Features Section</a> section for more advanced topics.</p> <script src="../markugen.js"></script> </body> </html>