If you are sick of overly complicated static site generators and you have a good working knowledge of publishing websites, then Grumpo might be for you!
We aim to support a very minimal feature set hopefully keeping the maintenance of this project low, and keeping you in control of your site.
Please be careful as this is a beta release and there may be serious bugs. Use at your own risk!
Grumpo is free and open source software and is published with no warranties of any kind! Please see License for details.
These instructions are appropriate for most developers. If you are having trouble, please see the Setup Details section below. Everything should be done in a shell application (terminal).
go get -u github.com/wrunk/grumpo
Provided your $GOPATH/bin (~/go/bin with Go modules) is in your path, test that
grumpo is installed and
working by typing grumpo to see the version and command usage.
If that doesn't work ensure $GOPATH/bin is in your path or file an issue.
If you don't know what GOPATH is, make sure you include ~/go/bin in your
PATH
Please create a directory specifically for this new website (let's call it mysite)
for the sake of this guide somewhere near where you create new software projects.
It might be better to do this outside of your gopath
Change directory to wherever you keep your projects
cd projects
Make a new mysite directory
mkdir mysite
Change into the new directory
cd mysite
Now create a new Grumpo project
grumpo init
Before you proceed, please use git to check all these files in.
You don't need to use github at this point, just git init, git add -A
and git commit to make a local commit in case you want to revert later.
Constant use of version control is highly recommended given the stateless
and minimal nature of Grumpo.
Open up your favorite IDE and explore what was created.
grumpo local
Will run a local development server to test your pages. This command will give you a special index to view.
If you notice on the __index__ page there are a few pages with their
metadata at the top (see metadata details below).
Hopefully examining the initial pages should give you a sense of how this all works.
In the static site generator world, a local page such as pages/about.md
would become /about/ on the server and should be linked to like that.
It is important to include the trailing / because that will tell the
web server to load /about/index.html
Originally I was trying to avoid having this section, but for even a semi-complicated site it's very necessary.
The metadata section is just a simple json object {...}. You can add single
line, c-style comments // so long as they are on their own line and within
the object.
Most fields besides live and title can just be skipped if not desired/needed.
{
// You can use c-style comments as long as they are on their own
// line and use the // format (not /**/)
// Title is ALWAYS required. You can control how this is used in
// base.html
"title": "Great Blog Post Aboot Cats!",
// Used in OG tags and can be used in recent posts promo
"desc": "Here is a short(ish) description about this article",
// Headlines can be used in various ways. More on this later
"hl1": "Headlines could be variations on title for",
"hl2": "a/b testing purposes or",
"hl3": "auto tweeting so you post your content multiple times spread out",
// Specify a relative or full URL to the article's canonical image.
// We'll set article's og:image tag to this
"image": "/static/img/hello.jpg",
"image_alt": "A hello face",
// If set to true, this page will go live with grumpo gen
// However it wont show up in recent posts until you set
// a publish date
"live": false,
// Both support the format 2020-01-01 OR 2020-01-01:03:04:05
// No other formats are supported and no timezones can be passed in
// grumpo commands use your machine's local time zone
"publish_date": "",
"updated_date": "",
// Tags, lower slug
"tags": [],
// Defaults to false. Set to true to treat this page as a full html page
"skip_base_template": false
}Once you have created some pages and are ready to push them to a server, do the following:
Run the Grumpo generation process:
grumpo gen
This will create a build/ directory with your entire site contained within. This could be uploaded to S3 or similar.
If you want to try using Google App Engine for free to host this, create a google cloud project and install the SDK then run:
gcloud app deploy --project=<project-name> ./app.yaml
Where you are replacing <project-name> with your GCP project name.
During the deploy you should see a note about a target url:
target url: [https://grumpo-dot-my-project.appspot.com]
Which once the deploy finishes should host your app.
All static files like js, css, fonts, and images should go in the static directory.
During a grumpo gen they will get copied to build/static/... directory
Usually you want to keep the different types in their own directory like
static/js/ static/img/ etc.
Consider reading the code (there's not that much of it), or checking out Grumpo
from Github and making some changes. You can mess around then run go install
and it will overwrite your grumpo command.
Of course you can also file an issue on Github and I will try to help.
Grumpo only works on UNIX-like operating system (so not windows). It was developed and tested on MacOS, so your milage may vary.
Make sure (assuming Go Modules):
~/go/binis in your path (sogo getorgo installwill make the grumpo command available)- You should really have git installed and use it constantly
- You have experience with html/css
- You have at least a basic command line working knowledge
- A simple static site generator
- With Markdown support
- And Html support (can use md or html files)
- Decent error checking for pages to make sure you don't totally screw up
- A minimal local development to make life easier
- A basic app engine setup that should let you deploy your app for free
- Unicode support via UTF8 markdown/html files
- Any support for user generated content. Grumpo assumes all content is trusted. I didn't bother using Go html templates for this reason
- A fancy local dev server. It is not designed to work with more than one user at a time and does not take any security precautions
- The project structure
- The grumpo command. This shouldn't be a huge deal if project structure stays the same. Likely grumpo command will need to improve to add needed features and fix bugs
- More errors/warnings about common publishing issues or things that could be improved
- Some sort of better image workflow. I don't really know what this means
yet, but generally speaking dealing with images in the online publishing world
SUCKS
- Keeping track of which image files go with which blogs
- Keeping track of where you got the image (source and license if not yours)
- Just making it easier to get that image you have in finder nicely organized in your blog project area
- Link to resources about modern web publishing like robots, seo, GA, GTM, ads, SEM, social, OG tags, etc
To run what few tests there are, simply go test -v
This is probably a reasonable request, but it does feel like it should just be another site altogether. For now not supported although I am working on a setting to skip the base template so you could make full pages within
- What if a page has css or js or html in it? will markdown lib just work and ignore that?
- Spaces in files names are going to not be bueno. Probably annoying but should only support a-z A-Z - 0-9 .
- Need to update files in init.go to reflect new json config process
- Sitemap generator
- RSS generator
- Create a robots.txt
- Also check to make sure each sub dir has an index
- Local server access logging
- 404 page support
- When HTML fails to validate, it breaks webserver. Also it has an unhelpful, crappy error message
- When rss, sitemaps, robots ready, include rules in app.yaml
- Home page should list out all pages/ to show how to use dynamic content
- Consider adding or at least commenting on anchorjs or how this could be done with markdown generator. https://github.com/bryanbraun/anchorjs
- Same with highlight.js
- Or perhaps use the server side highlighting
- Print an error if port 9876 is in use
These are just my personal notes for now and should move elsewhere soon.
- Setup outside gopath
- go mod init github.com/wrunk/grumpo
- go build to add deps
- How to pull down/install?