gostapagen

gostapagen (go-static-page-generator)

gostapagen is a tool that allows markdown content creators to do generate and expose statically generated pages.

More specifically, gostapagen is microservice written in Go that converts markdown files in a given git repository, converts them to html and exposes those statically rendered pages over a RESTful interface. It is operates on the principles of KISS and is best integrated in a JAMstack.

Prerequisites

Before you begin, ensure you have met the following requirements:

• You have installed the latest version of go1.16.5
• You have a Linux/Mac OS machine with working knowledge of the underlying filesystem and Go build process.

Installing gostapagen

If you want to try out on your local machine, you can simply install gostapagen system-wide with the following command:

$ ❯  go install -v ./...

Alternatively, you can build a binary and run that one with a configurable shell script. See how to build stapagen with the Makefile further down below (#Makefile).

Running gostapagen

To run gostapagen, follow these steps:

$ ❯  stapagen --repo=<content-git-repository-url> --branch=<branch>

Flags that you can use:

• --repo: The url to the git repository containing the markdown files. This repository is going to be cloned onto the filesystem by gostapagen. Make sure to use fully qualified without the .git extension at the end.

• --branch: The git branch that you want to use for the aforementioned repository.

• --clonePath: The absolute path to which the aforementioned git repository is going to be cloned to. Default path is /tmp.

• --contentDir: The relative path to the markdown files from within the git repository. Default value for this directory is /content.

• --port: Desired port to expose the RESTful api. Default port is /8080.

If you have build stapagen with the Makefile, you can simply adjust the parameters in the shell script stapagen.sh and then launch the script.

$ ❯  ./stapagen.sh

This method is preferable as you're more flexible and don't have to retype the binary arguments everytime.

Reading gostapagen's API

Once gostapagen is running, it does clone the git repository, converts its markdown files to html pages and forwards them over a RESTful api. That api can be accessed over locally if the executable was run on your local machine (http://localhost:8080) or over a K8s service definition.

• /generate: The generate endpoint does make an attempt at cloning the given git repository and directly converts the markdown files to html pages.

GET-Response:

{
  "success": true,
  "errors": []
}

• /pages: The pages endpoint exposes all available, read successfully converted pages in a json format.

GET-Response:

[
  {
    "title": "<title>",
    "permalink": "<permalink>",
    "author": "<author>",
    "tags": "<tag1, tag2, tag3>",
    "categories": "<cat1, cat2, cat3>",
    "publishDate": "<yyyy-mm-dd>",
    "description": "<description>",
    "showComments": "<true|false>",
    "isPublished": "<true|false>",
    "body": "<markdown rendered to html>"
  },
  {
    <secondpage>
  },
  ...
]

• /page?id=<permalink>: The page endpoint takes in an id query parameter where the value has to be the fully qualified permalink of the desired static page. As the /pages endpoint, this endpoint renders the page in a json format containing front matter data.

GET-Response:

 {
  "title": "<title>",
  "permalink": "<permalink>",
  "author": "<author>",
  "tags": "<tag1, tag2, tag3>",
  "categories": "<cat1, cat2, cat3>",
  "publishDate": "<yyyy-mm-dd>",
  "description": "<description>",
  "showComments": "<true|false>",
  "isPublished": "<true|false>",
  "body": "<markdown rendered to html>"
}

• /status: The status endpoint exposes a range of technical information about the generation feature.

GET-Response:

{
  "totalPages": 42,
  "publishedPages": 38,
  "unpublishedPages": 4,
  "lastPublishedPage": "2021-06-20",
  "lastGeneratedAt": "2021-06-25 10:22:42.603814 +0200 CEST m=+178.298962869"
}

Makefile

There is a Makefile which automates the building process of the stapagen application. The Makefile has 6 build targets: test, vet, fmt, mod, build, run, install and all. It can simply be run as such:

$ ❯  make build

Dockerfile

There is also a Dockerfile by which one can containerize the stapagen application. The port that is being exposed is the default 8080.

Deployment to K8s

{coming soon}

Quick Deployment to DigitalOcean's Kubernetes

Contributing to gostapagen

To contribute to gostapagen, follow these steps:

1. Fork this repository.
2. Create a branch: git checkout -b <branch_name>.
3. Make your changes and commit them: git commit -m '<commit_message>'
4. Push to the original branch: git push origin <project_name>/<location>
5. Create the pull request.

Alternatively see the GitHub documentation on creating a pull request .

Contributors

Thanks to the following people who have contributed to this project:

• @raffaelschneider 💻📖🐛
• @stefanwelsch 💻🧑‍🏫
• @tomtrapp 🤔👀
• @rickyelfner 💬🐛

You might want to consider using something like the All Contributors specification and its emoji key.

Contact

If you want to contact me you can reach me at [email protected].

License

This project uses the following license: MIT License . https://opensource.org/licenses/MIT