barf

Running `barf` on OpenBSD

Sat, 12 Aug 2023 00:00:00 +0000

Running `barf` on OpenBSD

2023-08-12

The barf project was built on Linux and was catered towards Linux users. The core of the project will remain focused on Linux/GNU tools, but I also need to support OpenBSD since that is my personal operating system of choice.

Download Packages

Along with your Markdown parser of choice (barf assumes you will be using my version of smu) you will also need to install the required packages on your OpenBSD system:

doas pkg_add rsync coreutils gsed cmake gcc
+

Then ensure that you alter all instances of sed with gsed in the core barf file. (Or make an alias if you'd prefer not to alter the main file)

After that, everything should work perfectly fine when building!

Markdown Examples in barf

Thu, 05 Jan 2023 00:00:00 +0000

Markdown Examples in barf

2023-01-05

This following was lifted from https://github.com/karlb/smu

`smu` Syntax

smu was started as a rewrite of +markdown but became something +more lightweight and consistent. It differs from CommonMark in the following ways:

No support for reference style links
Stricter indentation rules for lists
Lists don't end paragraphs by themselves (blank line needed)
Horizontal rules (<hr>) must use - - - as syntax
Code fences have stricter syntax

Patches that increase the CommonMark compatibility are welcome as long as they don't increase the code complexity significantly.

This project is a fork of the original smu by +Enno Boland (gottox). The main differences to the +original smu are:

Support for code fences
Improved CommonMark compatibility. E.g. +
- Code blocks need four spaces indentation instead of three
- Skip empty lines at end of code blocks
- Ignore single spaces around code spans
- Keep HTML comments in output
- Improved spec compliance for lists
- Nesting code block in blockquotes works
- "Empty" lines in lists behave identically, no matter how much whitespace they contain
- No backslash escapes in code blocks
- Use first number as start number for ordered lists
+
Added a simple test suite to check for compliance and avoid regressions

Inline patterns

There are several patterns you can use to highlight your text:

Emphasis
+ +
- Surround your text with * or _ to get emphasised text: +
```
This *is* cool.
+This _is_ cool, too.
+
```
  +
- Surround your text with ** or __ to get strong text: +
```
This **is** cool.
+This __is__ cool, too.
+
```
  +
- Surround your text with *** or ___ to get strong and emphasised text: +
```
This ***is*** cool.
+This ___is___ cool, too.
+
```
  +
- But this example won't work as expected: +
```
***Hello** you*
+
```
  +
  This is a wontfix bug because it would make the source too complex. +Use this instead: +
  +
```
***Hello*** *you*
+
```
  +
+
inline Code
+
You can produce inline code by surrounding it with backticks.
+
```
Use `rm -rf /` if you're a N00b.
+Use ``rm -rf /`` if you're a N00b.
+Use ```rm -rf /``` if you're a N00b.
+
```
+
Double and triple backticks can be used if the code itself contains backticks.
+

Titles

Creating titles in smu is very easy. There are two different syntax styles. The +first is underlining with at least three characters:

Heading
+=======
+
+Topic
+-----
+

This is very intuitive and self explaining. The resulting sourcecode looks like +this:

<h1>Heading</h1>
+<h2>Topic</h2>
+

Use the following prefixes if you don't like underlining:

# h1
+## h2
+### h3
+#### h4
+##### h5
+###### h6
+

Links

The simplest way to define a link is with simple <>.

<http://s01.de>
+

You can do the same for E-Mail addresses:

<yourname@s01.de>
+

If you want to define a label for the url, you have to use a different syntax

[smu - simple mark up](http://s01.de/~gottox/index.cgi/proj_smu)
+

The resulting HTML-Code

<a href="http://s01.de/~gottox/index.cgi/proj_smu">smu - simple mark up</a></p>
+

Lists

Defining lists is very straightforward:

* Item 1
+* Item 2
+* Item 3
+

Result:

<ul>
+<li>Item 1</li>
+<li>Item 2</li>
+<li>Item 3</li>
+</ul>
+

Defining ordered lists is also very easy:

1. Item 1
+2. Item 2
+3. Item 3
+

Only the first number in a list is meaningful. All following list items are +continously counted. If you want a list starting at 2, you could write:

2. Item 1
+2. Item 2
+2. Item 3
+

and get the following HTML which will render with the numbers 2, 3, 4:

<ol start="2">
+<li>Item 1</li>
+<li>Item 2</li>
+<li>Item 3</li>
+</ol>
+

Code & Blockquote

Use the > as a line prefix for defining blockquotes. Blockquotes are +interpreted as well. This makes it possible to embed links, headings and even +other quotes into a quote:

> Hello
+> This is a quote with a [link](http://s01.de/~gottox)
+

Result: +

<blockquote><p>
+Hello
+This is a quote with a <a href="http://s01.de/~gottox">link</a></p>
+</blockquote>
+

You can define a code block with a leading Tab or with 4 leading spaces

	this.is(code)
+
+    this.is(code, too)
+

Result: +

<pre><code>this.is(code)</code></pre>
+<pre><code>this.is(code, too)
+</code></pre>
+

Please note that you can't use HTML or smu syntax in a code block.

Another way to write code blocks is to use code fences:

```json
+{"some": "code"}
+```
+

This has two advantages:

+ +

The optional language identifier will be turned into a language- class name
You can keep the original indentation which helps when doing copy & paste

Tables

Tables can be generated with the following syntax:

| Heading1 | Heading2 |
+| -------- | -------- |
+| Cell 1   | Cell2    |
+

Aligning the columns make the input nicer to read, but is not necessary to get +correct table output. You could just write

| Heading1 | Heading2 |
+| --- | --- |
+| Cell 1 | Cell2 |
+

To align the content of table cells, use |:--| for left, |--:| for right +and |:--:| for centered alignment in the row which separates the header from +the table body.

| Heading1 | Heading2 | Heading3 |
+| :------- | :------: | -------: |
+| Left     | Center   | Right    |
+

Other interesting stuff

to insert a horizontal rule simple add - - - into an empty line:
+
```
Hello
+- - -
+Hello2
+
```
+
Result: +
+
```
<p>
+Hello
+<hr />
+
```
+
```
Hello2</p>
+
```
+
Any ASCII punctuation character may escaped by precedeing them with a +backslash to avoid them being interpreted:
+
```
!"#$%&'()*+,-./:;<=>?@[]^_`{|}~\
+
```
+
To force a linebreak simple add two spaces to the end of the line:
+
```
No linebreak
+here.
+But here is  
+one.
+
```
+

embed HTML

You can include arbitrary HTML code in your documents. The HTML will be +passed through to the resulting document without modification. This is a good +way to work around features that are missing in smu. If you don't want this +behaviour, use the -n flag when executing smu to stricly escape the HTML +tags.

Running `barf` on MacOS

Wed, 18 Jan 2023 00:00:00 +0000

Running `barf` on MacOS

2023-01-18

The barf project was built on Linux and was catered towards Linux users. The core of the project will remain focused on Linux/GNU tools, but that doesn't mean MacOS needs to be left out in the cold.

There are some very minor changes you'll need to make to your default sed and date paths if you plan to run barf on MacOS.

Download Packages

This walkthrough assumes that you already have homebrew installed on your machine.

You will need to install the GNU versions of both date and sed in order to avoid breaking things when barf tries to build.

brew install coreutils
+brew install gnu-sed
+

Setting `gsed` and `gdate` as Default

Now run the following in a terminal shell:

sudo ln -fs /opt/homebrew/bin/gsed /usr/local/bin/sed
+sudo ln -fs /opt/homebrew/bin/gdate /usr/local/bin/date
+

and add the following to your .bash_profile file:

export PATH="/usr/local/bin:$PATH"
+

Reload your bash instance and everything should work as intended!

Supporting Basic Dark Mode

Tue, 07 Mar 2023 00:00:00 +0000

Supporting Basic Dark Mode

2023-03-07

The default barf site generator now supports basic dark mode functionality. This has been achieved by including the standard color-scheme meta tag in the core header.html file:

<meta name="color-scheme" content="dark light">
+

This change also ships with some minor updates to the default blockquote design. You can see an example below:

This is a really cool blockquote
+

Minor Caveat

Unfortunately, Safari still has minor ahref / link color issue when defaulting to browser dark mode. If this is a problem for your own build of barf, take a look at a solution I wrote about here.

Personally, I can't be bothered to add that extra code to this project. The Safari team needs to get their shit together and fix such a simple bug. Plus, you shouldn't be using Safari anyway - it's proprietary garbage.

Cleaning Up barf's Structure

Mon, 09 Oct 2023 00:00:00 +0000

Cleaning Up barf's Structure

2023-10-09

Things probably look a little different around here. Both in terms of this demo site and the core barf files itself.

This project was always intended to be focused on Linux platforms. So, I've removed the included barf_macos and barf_openbsd files to keep the generator more streamlined. But have no fear! Instructions for both Mac and OpenBSD can still be found on the main blog:

As for the "default" look of barf, I've simplified things further. The total CSS styling now consists of only:

*{box-sizing:border-box;}
+body{font-family:sans-serif;margin:0 auto;max-width:650px;padding:1rem;}
+img{max-width:100%;}
+pre{overflow:auto;}
+

Users still have the ability to tweak things as much as they'd like, but the standard look should be more than enough for anyone just focusing on writing. Dark mode has also been dropped but is easily added by adding the following inside the head tags:

<meta name="color-scheme" content="dark light">
+

Hopefully these changes reduce the overall scope of the project, which was a main point made on the README originally!

barf

Running `barf` on OpenBSD

Running barf on OpenBSD

Download Packages

Markdown Examples in barf

Markdown Examples in barf

smu Syntax

Inline patterns

Titles

Links

Lists

Code & Blockquote

Tables

Other interesting stuff

embed HTML

Running `barf` on MacOS

Running barf on MacOS

Download Packages

Setting gsed and gdate as Default

Supporting Basic Dark Mode

Supporting Basic Dark Mode

Minor Caveat

Cleaning Up barf's Structure

Cleaning Up barf's Structure

Running `barf` on OpenBSD

`smu` Syntax

Running `barf` on MacOS

Setting `gsed` and `gdate` as Default