#static-site-generator #site #static

app strawberrymilk

A small, sweet tool written in Rust to compile your content for the web

3 stable releases

1.2.0 Mar 15, 2022
1.1.0 Mar 12, 2022
1.0.0 Mar 12, 2022

#2462 in Command line utilities

MIT license

21KB
250 lines

STRAWBERRY MILK

A small, sweet tool written in Rust to compile your content for the web.

GitHub CI

ABOUT

Since I am also an author and artist, I was wondering how I would write a small program that turns files with content written in Markdown into a website. Strawberry Milk is that tool. You initialize a new project, write your content in Markdown, run Strawberry Milk and voilá! You have a nice and shiny new webpage that has your content in it, styled and ready for the world!

EXAMPLE PROJECT

You can view a live, deployed Strawberry Milk project here.

BUILDING

Tools

You will need the following tools installed and available:

  • Rust
  • Git

Steps

  • 1.) Get the source code:
$ git clone https://github.com/iamtheblackunicorn/strawberrymilk.git
  • 2.) Change directory:
$ cd strawberrymilk
  • 3.) Build the source code:
$ cargo build --release

INSTALLATION

Move the executable on the path strawberrymilk/target/release/strawberrymilk to the directory where you keep your binary executables. If you are on Linux or Mac OSX, you might have to change permissions like this: chmod a+x strawberrymilk. If you have Rust's package manager installed, running cargo install strawberrymilk from a terminal window should also install Strawberry Milk.

USAGE

Command-line usage

To compile your project, simply run this command on the command-line:

$ strawberrymilk yourprojectdir

yourprojectdir represents the path of your project.

Creating a new project.

To create a new project, run the following command:

$ strawberrymilk new myproject

This will create a new folder called myproject. Your project's file structure will look something like this:

myproject
├── config.json
└── content
    └── 01.markdown

The file, config.json, will contain the following:

{
  "styles": "https://blckunicorn.art/assets/generic/strawberrymilk.css",
  "content": "content",
  "name": "myproject",
  "output": "index.html"
}
  • name: What is your project called?
  • content: Which sub-folder contains the project's Markdown files?
  • styles: To make your content look pretty, you need a stylesheet. Load this from somewhere else. Strawberry Milk doesn't support local stylesheets.
  • output: What is the output HTML file supposed to be called?
  • use_template: If you would like to use a Liquid template, set this to true or false.
  • template_path: This field tells Strawberry Milk where your template is located in the project.

Next, open up 01.markdown located in the content folder. (Please note that this folder's name has to be the same as the content field in the configuration file.) It will contain something like this:

# YOUR PROJECT
Your awesome content goes here.

If you are using a template, all variables from the configuration file are available under {{ project.variable }}. variable represents the field name from your config.json file.

To iterate over the content in the template like this for example:

{% for page in pages %}
<br/>
<div class="content">
  {{ page.content }}
</div>
<br/>
{% endfor %}

Strawberry Milk gives you access to your content via the {{ pages }} variable. Note that Strawberry Milk will "panic" if you make any mistakes.

You can now fill this out and create Markdown files with numerical filenames (01.markdown,02.markdown,03.markdown, etc.) and when you are done, you can run this command in the project's root directory:

$ strawberrymilk .

If everything is A-OK, you should now have a file called index.html in a sub-directory called build.

Deployment to GitHub Pages.

If you have a GitHub account, you can upload your project to a repository, create a new branch called gh-pages, create a new file called rust.yml at .github/workflows in your repository, fill it with the code below, and voilá: You can now view your project on the web under the URL of yourusername.github.io/yourporject.

on: [push]
name: Strawberry Milk Project CI
jobs:
  build_and_test:
    name: Strawberry Milk Project CI
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - uses: actions-rs/cargo@v1
        with:
          command: build
          args: --release
      - uses: actions-rs/cargo@v1
        with:
          command: run
          args: .
      - name: Deploy
        uses: JamesIves/github-pages-deploy-action@v4.2.5
        with:
          branch: gh-pages
          folder: build

CONTRIBUTING

If you have some suggestions for improvement or you want to contribute, either file an issue or fork the repository. If you want to do the latter, make and test your changes, and file a Pull Request.

CHANGELOG

Version 1.0.0

  • Initial release.
  • Upload to GitHub.

Version 1.1.0

  • Updated documentation.
  • Upload to crates.io.

Version 1.2.0

  • Added custom-templating.
  • Users can add their own templates and use them.

NOTE 📜

  • Strawberry Milk by Alexander Abraham a.k.a. "The Black Unicorn"
  • Licensed under the MIT license.

Dependencies

~10MB
~190K SLoC