So you’ve got your shiny new jekyll-based site, and it’s got some css and probably just the default “hello world” post on it (I’m assuming it’s a site I helped you set up, or that you set it up from my skeletonizer, because otherwise how would you find this post?), and you realize: how to I post?

That’s what this post is for.

For those who have used github before:

1. Create a markdown file with the name ‘YYYY-MM-DD-topic-of-post.md’
2. put in the front matter (example below)
3. write your post in markdown
4. save the file
5. (Optional) run the python script to sync up your topics/create your topic pages.
6. Create a commit, push your changes.

For those who have not used github before:

It’s a real xkcd-geochemists moment here, but I’ve since realized that the method descriped in this section is not actually the simplest way to do it. It’s a decent explanation of how to post from a text file on your computer but i’ve actually found that showing people how to just use the web version of github is a lot simpler. So watch for an updated version of this post with information on how to do that, especially if you find/found this section confusing.

Hi! I’m pretty sure you’re in the majority here, so don’t worry! I’m going to do my best to be very clear about what you should do. I’ll include screenshots, too, in a little bit. (I want to do it over Windows, because if you use linux you probably know what you’re doing).

Okay, so the first thing you’re going to do, is download github desktop. Download whatever version is appropriate for your operating system.

Next, make a copy of the repository of your site’s code on your hard drive. Do this by clicking the button that says “TK”. This downloads all the files that make up your website to your computer, so you can edit them offline.

Now, navigate to the “_posts” directory (folder). In it you’re going to see a file with a name that’s something like 2023-09-29-hello-world.md. This is a markdown file.

If you’ve formatted messages in Discord, you’ve used markdown. If you haven’t, don’t worry! It’s very simple. Basically, you’re going to add some extra punctuation around your words so that your site knows when to display something as bold or italic or even a

heading.

Each of your posts will be written in their own markdown file. Go ahead and create one now. You can do this on Windows by creating a new text file, and then editing the file ending (.txt) to be .md.

You should name your file with today’s date in the YYYY-MM-DD format, and then what the title of your post will be. For example, this post is written in a file called 2023-09-29-how-2-post.md. Put dashes to the words and numbers, but don’t worry about your posts’s title showing-up-like-this. The dashes will get taken out when Jekyll* processes it.

*Jekyll is basically the program that github uses to turn your markdown files into posts.

Front matter

Jekyll uses a section called front matter at the top of each of your markdown files to know who wrote it, and that this file should be turned into a post. All you need to do is put:

--- layout: post author: your-name ---

at the top of your file, before you’ve written anything else, and you’re good.

Example:

The front matter of this post’s markdown file looks like this:

--- layout: post author: mossbeasts ---

Now, you get to write the post!

Writing the post

I assume you know what you’re going to say, so this section is to show you how to format it with things like bold text or italic text.

As you’re writing, you can add in some markdown code to format your post. Here’s what I use most often:

effect	how to do it	what it looks like
italics	*italics* or _italics_	italics
bold	**bold**	bold
link	[link text](link url) (make sure you include the “https://”	example.com

To do headings, just put a # in front of your text. For example,

# heading 1

will show up as

heading 1

and ## heading 2

will show up as

heading 2.

Tip: Make sure that you hit enter to create a blank line between your paragraphs and your headings. Otherwise, your spacing can get weird when you public your post.

# the right thing to do

is this

and this

# you don't want to do it like this or this

Once you’ve written your post and have it formatted how you’d like, it’s time to public it.

Publishing your post

First, save your file.

Second, you’re going to add it to your repository - the online copy of the files that make up your website.

Section with screenshots on how to do this tk when i’m on a windows computer.

And that’s it!

Special case: you use topics

If you use topics like the ones on my blog, you’re going to have two extra steps.

front matter

First, add a section to your front matter with the tags. This is what the tags for this post look like:

tags: computers documentation

Tags are separated by spaces. If you want to have a multi-word tag/topic, write it with quotes around it.

Example:

tags: "more than one word" tag

Both “more than one word” and tag will act like their own topics.

collecting your tags

Once you’ve saved and closed your file, run tagcrawl.py, which should have been downloaded with the rest of your site. On mac, do this by tapping with two fingers to open up the menu, hitting open a terminal in this location (or whatever the actual message says), and typing in python tagcrawl.py. Then hit enter, and the program will run.

(tagcrawl.py is a python script I got from here.)

after you’ve added the tags to your front matter and run the python script, just public your post like normal.

I can - and will - delete any comment at any time for any reason I want. Write comments that won't make me want to delete them.

Also, refer to people with initials or with their github username. I'd like to maintain the thin veneer of possible anonymity this site currently has.