web-bud

Usage

Quick start
File structure
Templating features
Markdown features

Quick start

Quick start ↑{#quick-start}

Make sure you have Node installed (I only tested on v18.20+).
Grab and unzip the latest release or do a git clone.
Open your terminal in the web-bud folder and use npm i to install the dependency.
Use npm run watch, then open localhost:8000 to see your website! Edit things and watch the page reload automatically.
When you're happy with your website, use npm run build to get the final build in the dist folder. Careful, if you try npm run watch again it will replace that build!

I tried to document the code fairly extensively, so you should be able to figure out how most things work. Mess around, and let me know if you make something cool out of it!

File structure

File structure ↑{#file-structure}

dist: where web-bud places and serves the built website
public: any static files (fonts, images, favicons)
src
- /components: reusable components (ex. site header and footer)
- /content: the actual pages
- /styles: CSS files. If you split them and use @import rules in a main file, the imports will be combined in the final build!
- /templates: HTML template files. Pages can use different templates!
- data.js: add logic to grab/generate data here. The data object it exports is available in your templates and content
- data.json: custom data to inject
base.html: The base template used by all pages, where you will usually add the <html> and <head>
config.json: Some dev-related configuration can be found there

Your website page structure follows the files and folders in src/content.

src/content/welcome.md will become site.url/welcome
src/content/hello/index.md will become site.url/hello
src/content/hello/world.md will become site.url/hello/world

Templating features

Templating features ↑{#templating-features}

web-bud uses a few simple tags to allow some templating. Variables are made available at build time in a data object. You can add anything you want to it with src/data.js and src/data.json.

{{data.variable}} will display the value of data.variable
{{for item in data.list}} [...] {{/for}} will loop through items in data.list
{{if data.value}} [...] {{else if data.value2}} [...] {{/if}} will check if data.value or data.value2 are true/truthy
{{components.name-of-component}} will display src/components/name-of-component.html
{{content}} will display the page content
{{markup}} will display the page template

Markdown files in src/content use frontmatter at the top of the file, with a few useful fields:

name: the page name, used for internal reference (for ex. in wiki-style links)
template: which template to use from src/templates. If not defined, default.html will be used
title: the page meta title
meta: used if you wish to add meta tags (typically description)

Markdown features

Markdown features ↑{#markdown-features}

web-bud uses custom Markdown with a small handmade parser. It probably has bugs and does not support the entire Markdown syntax, so please submit an issue if you'd like something fixed or added!

IDs and classes

You can usually add an ID and classes to blocks and elements.

# Chicken
{#title}

My chicken looks like this:
{.centered .red}

![A cute chicken](/chicken.jpg){width=100 height=100}{.rounded}

<h1 id="title">Chicken</h1>

<p class="centered red">
  My chicken looks like this:
</p>

<p>
  <img class="rounded" src="/chicken.jpg" alt="A cute chicken" width="100" height="100" />
</p>

Titles

# Main title
## Secondary title
### Tertiary title
#### Quaternary title

<h1>Main title</h1>
<h2>Secondary title</h2>
<h3>Tertiary title</h3>
<h4>Quaternary title</h4>

Paragraphs

This is a paragraph.

<p>This is a paragraph.</p>

Lists

- Item one
- Item two

<ul>
  <li>Item one</li>
  <li>Item two</li>
</ul>

Ordered lists

1. Item one
2. Item two
1000. Item two

<ul>
  <li>Item one</li>
  <li>Item two</li>
</ul>

Definition lists

Definition title
: definition one
: definition two

<dl>
  <dt>Definition title</dt>
  <dd>definition one</dd>
  <dd>definition two</dd>
</dl>

Blockquotes

You can optionally add a source/author at the end with >-.

> “One could describe Design as a plan for arranging elements to accomplish a particular purpose.”
>- Charles Eames

<blockquote>
  <p>“One could describe Design as a plan for arranging elements to accomplish a particular purpose.”</p>
</blockquote>
<p class="blockquote-author">— Charles Eames</p>

Horizontal rules

--- or *** → <hr>

Images

![A dotted frog sitting next to a pond](/assets/images/frog.png){width=100 height=100 loading=lazy}

<img src="/assets/images/frog.png" alt="A dotted frog sitting next to a pond" width="100" height="100" loading="lazy">

Figures

Use a ? at the start of a line to turn it into the figcaption.

??
![A pigeon trying their best to build a nest](/assets/images/pigeon.jpg){width=100 height=100}
? Beautiful pigeon I saw in my neighbourhood.
??

<figure>
  <img src="/assets/images/pigeon.jpg" alt="A pigeon trying their best to build a nest" width="100" height="100">
  <figcaption>Beautiful pigeon I saw in my neighbourhood.</figcaption>
</figure>

Links

Check out [my frogs collection](/frogs)

Check out <a href="/frogs">my frogs collection</a>

Wiki-style links

You can link directly to a page on your site using its name (set in frontmatter).

[[Home]]

<a href="/home">Home</a>

Bold text

Use <b> to draw more attention on the words:

This place is **sacred** in ancient legends.

This place is <b>sacred</b> in ancient legends.

Use <strong> to insist on something serious/important:

Please !!do not enter!! the area.

Please <strong>do not enter</strong> the area.

Italic text

Use <em> to denote/put emphasis on specific words:

They were *particularly* happy that day.

They were <em>particularly</em> happy that day.

Highlighted text

According to a witness, ==the door was fractured==.

According to a witness, <mark>the door was fractured</mark>.

Deleted text

My ~~friend~~ bestie is here.

My <del>friend</del> bestie is here.

Small text

--All photos in this article are edited.--

<small>All photos in this article are edited.</small>

Code and code blocks

Use backticks to insert inline code.

Use a `for` loop

Use a <code>for</code> loop

Use double backticks if the code contains backticks.

They used  ``run `test` --dev``

They used <code>run `test` --dev</code>

Use triple backticks to insert a code block.

```
function example() => true
```

<pre><code>function example() => true</code></pre>

Escape characters

Use backslashes to escape characters and prevent them from being parsed as Markdown.

This text won't be \*\*bold\*\*

This text won't be **bold**

Return to top ↑