~swisschili/blackjack

8ab3a0709529eda6e5133cb79e3da979e8d238cc — swissChili 5 months ago 6f6ae0c
Add docs
M .gitignore => .gitignore +1 -0
@@ 3,3 3,4 @@ templates
content
static
!docs
!docs/*

A docs/content/index.md => docs/content/index.md +95 -0
@@ 0,0 1,95 @@
@parent = index.html
@title = Home

# Blackjack Docs

Blackjack is a simple, fast, and extremely extensible static site generator written in Lua.
It's goals are to be as simple as possible, while maintaining a high level of usability and
scalability.

### Who should use Blackjack?

If you're tired of bloated software and want a simple static site generator that puts you in
control, blackjack is for you.

### Who shouldn't use Blackjack?

If you're looking for a lot of advanced features and don't want to write any code yourself,
blackjack probably isn't for you. If you want to make a static blog you should probably use
Jekyll.

## Getting Started

### Installation

First install Lua. You will need blackjack.lua to be in your lua path in order for your
configuration files to work. At some point I will deploy this to LuaRocks.

### Configuration

Blackjack is a Lua module, not a standalone program. This means that to build your site, you
will need to write a very simple lua program. Don't worry if you don't know Lua, it's a very
simple language and you won't need to touch anything complicated to write configuration files.

Here is the simplest blackjack config:

```
require "blackjack"
Site:build()
```
Site is an object that has some configuration data that influence how your site is build. When
you run Site:build(), blackjack uses that information to build your static site.

By default, Site looks like this:

```
Site = {
  -- Template source directory
  templates = "templates",
  -- Content source directory
  content = "content",
  -- Output directory
  output = "site",
  -- Static file directory
  static = nil,
  -- File processor objects
  processors = {
    html = {
      process = htmlProcessor,
      extension = 'html'
    },
    md = {
      process = mdProcessor,
      extension = 'html'
    }
  }
}
```
The first four fields are pretty self explanatory, they just set what directories blackjack
will look for files in.

The processors table is a little more interesting. Processors are functions that blackjack
uses to transform input content into output content—usually html.

The built-in processors htmlProcessors and mdProcessors transform HTML templates and Markdown
into HTML. These are included with blackjack because of how common they are.

It is trivial to define your own processors, you don't even have to use Lua!

For example, here's how you would define a processor that takes sass files as input and
generates css:

```
Site.processors.sass = {
  process = cmdProcessor("sass -"),
  extension = "css"
}
```
The cmdProcessor function is a helper for defining processors that invoke other commands.
This has some disadvantages: mainly that such processors won't have access to the defined
variables, and won't be able to take advantage of templates. Commands invoked through such
processors are given the content of the input file through standard input and are expected
to provide generated output through standard output.

This very same sass processor is used to build this website. That's how easy it is to add
functionality to blackjack!

A docs/content/styles.scss => docs/content/styles.scss +31 -0
@@ 0,0 1,31 @@
html,
body {
  font-family: 'Segoe UI', 'Roboto', 'San Francisco', 'IBM Plex Sans', 'sans-serif';
}

body {
  display: grid;
  place-items: center center
}

.container {
  width: 50vw;
}

.nav {
  font-size: 1.5rem;
  display: flex;
  flex-direction: row;

  .wide {
    flex: 1;
    font-weight: bold;
  }
}

@media screen and (max-width: 960px) {
  .container {
    width: calc(100% - 2em);
    margin: 1em;
  }
}

A docs/site/index.html => docs/site/index.html +106 -0
@@ 0,0 1,106 @@
<html>
  <head>
    <link rel="stylesheet"
      href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/styles/default.min.css">
    <link rel="stylesheet" href="styles.css">
    <title>Home</title>
  </head>
  <body>
    <div class="container">
      <div class="nav">
        <a href="/" class="wide">Blackjack</a>
        <a href="https://git.sr.ht/~swisschili/blackjack">Git</a>
      </div>
      <hr>
      <h1> Blackjack Docs</h1>
Blackjack is a simple, fast, and extremely extensible static site generator written in Lua.
It's goals are to be as simple as possible, while maintaining a high level of usability and
scalability.
<br>
<h3> Who should use Blackjack?</h3>
If you're tired of bloated software and want a simple static site generator that puts you in
control, blackjack is for you.
<br>
<h3> Who shouldn't use Blackjack?</h3>
If you're looking for a lot of advanced features and don't want to write any code yourself,
blackjack probably isn't for you. If you want to make a static blog you should probably use
Jekyll.
<br>
<h2> Getting Started</h2>
<h3> Installation</h3>
First install Lua. You will need blackjack.lua to be in your lua path in order for your
configuration files to work. At some point I will deploy this to LuaRocks.
<br>
<h3> Configuration</h3>
Blackjack is a Lua module, not a standalone program. This means that to build your site, you
will need to write a very simple lua program. Don't worry if you don't know Lua, it's a very
simple language and you won't need to touch anything complicated to write configuration files.
<br>
Here is the simplest blackjack config:
<br>
<pre><code class>require "blackjack"
Site:build()</code></pre>
Site is an object that has some configuration data that influence how your site is build. When
you run Site:build(), blackjack uses that information to build your static site.
<br>
By default, Site looks like this:
<br>
<pre><code class>Site = {
  -- Template source directory
  templates = "templates",
  -- Content source directory
  content = "content",
  -- Output directory
  output = "site",
  -- Static file directory
  static = nil,
  -- File processor objects
  processors = {
    html = {
      process = htmlProcessor,
      extension = 'html'
    },
    md = {
      process = mdProcessor,
      extension = 'html'
    }
  }
}</code></pre>
The first four fields are pretty self explanatory, they just set what directories blackjack
will look for files in.
<br>
The processors table is a little more interesting. Processors are functions that blackjack
uses to transform input content into output content—usually html.
<br>
The built-in processors htmlProcessors and mdProcessors transform HTML templates and Markdown
into HTML. These are included with blackjack because of how common they are.
<br>
It is trivial to define your own processors, you don't even have to use Lua!
<br>
For example, here's how you would define a processor that takes sass files as input and
generates css:
<br>
<pre><code class>Site.processors.sass = {
  process = cmdProcessor("sass -"),
  extension = "css"
}</code></pre>
The cmdProcessor function is a helper for defining processors that invoke other commands.
This has some disadvantages: mainly that such processors won't have access to the defined
variables, and won't be able to take advantage of templates. Commands invoked through such
processors are given the content of the input file through standard input and are expected
to provide generated output through standard output.
<br>
This very same sass processor is used to build this website. That's how easy it is to add
functionality to blackjack!
    </div>

    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/highlight.min.js"></script>
    <script>
      document.addEventListener('DOMContentLoaded', (event) => {
        document.querySelectorAll('pre code').forEach((block) => {
          hljs.highlightBlock(block);
        });
      });
    </script>
  </body>
</html>

A docs/site/styles.css => docs/site/styles.css +30 -0
@@ 0,0 1,30 @@
html,
body {
  font-family: "Segoe UI", "Roboto", "San Francisco", "IBM Plex Sans", "sans-serif";
}

body {
  display: grid;
  place-items: center center;
}

.container {
  width: 50vw;
}

.nav {
  font-size: 1.5rem;
  display: flex;
  flex-direction: row;
}
.nav .wide {
  flex: 1;
  font-weight: bold;
}

@media screen and (max-width: 960px) {
  .container {
    width: calc(100% - 2em);
    margin: 1em;
  }
}

A docs/templates/index.html => docs/templates/index.html +27 -0
@@ 0,0 1,27 @@
<html>
  <head>
    <link rel="stylesheet"
      href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/styles/default.min.css">
    <link rel="stylesheet" href="styles.css">
    <title>${title}</title>
  </head>
  <body>
    <div class="container">
      <div class="nav">
        <a href="/" class="wide">Blackjack</a>
        <a href="https://git.sr.ht/~swisschili/blackjack">Git</a>
      </div>
      <hr>
      ${body}
    </div>

    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.18.1/highlight.min.js"></script>
    <script>
      document.addEventListener('DOMContentLoaded', (event) => {
        document.querySelectorAll('pre code').forEach((block) => {
          hljs.highlightBlock(block);
        });
      });
    </script>
  </body>
</html>