web-bud

Usage

Quick start
File structure
Templating features
Syntax features

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 update 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 ↑

bin: web-bud lives here
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>
budconfig.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 ↑

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)

Syntax features

Syntax features ↑

web-bud uses a Markdown-like syntax. Its small, handmade parser probably has bugs, so please submit an issue if you'd like something fixed or added!

IDs and classes

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

# My chicken
{#title}

- Bella{.red}
- Maria
{.cool-list .centered}

<h1 id="title">My chicken</h1>

<ul class="cool-list centered">
  <li class="red">Bella</li>
  <li>Maria</li>
</ul>

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.
There is text in it.

This is another paragraph.

<p>
  This is a paragraph. There is text in it.
</p>

<p>
  This is another 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
8. Item three

<ol>
  <li>Item one</li>
  <li>Item two</li>
  <li>Item three</li>
</ol>

Definition lists

Definition title
: definition one
: definition two
Other definition title
: definition three

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

Blockquotes

You can optionally add a source with >-.

>>>
Sent at 2pm:

Hello!
>>>

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

<blockquote>
  <p>Sent at 2pm:</p>
  <p>Hello!</p>
</blockquote>

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

Horizontal rules

--- or *** → <hr>

Images

![A dotted frog in a pond](/frog.png){width=100 height=100 loading=lazy}

<img src="/frog.png" alt="A dotted frog in 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 building a nest](/pigeon.jpg){width=100 height=100}
? Cute pigeon in my neighbourhood.
???

<figure>
  <p>
    <img src="/pigeon.jpg" alt="A pigeon building a nest" width="100" height="100">
  </p>
  <figcaption>Cute pigeon 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>

Reference links

This sentence has a source.[^1] This one too.[^B]

[^1: My Neat Reference, 2025. [Link](https://my-reference.neat)]
[^B: Old Reference, 400 BCE.]

<p>
  This sentence has a source.<sup><a id="ref_1" href="#footnote_1">[1]</a></sup> This one too.<sup><a id="ref_B" href="#footnote_B">[B]</a></sup>
</p>

<p>
  <span id="footnote_1">
    1. <a href="#ref_1">↑</a> My Neat Reference, 2025. <a href="https://my-reference.neat">Link</a>
  </span>
  <span id="footnote_B">
    B. <a href="#ref_B">↑</a> Old Reference, 400 BCE.
  </span>
</p>

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>

Preformatted text

Use three single quotes to keep whitespace in text.

'''
This will
    keep spaces
        as written
'''

<pre>
This will
    keep spaces
        as written
</pre>

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 three 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 ↑