Okay, let’s try this again. I previously tried to write a post explaining how to post on a github pages site for people who’d never worked with github, markdown, or a cli before, but I’m not happy with it. It’s a fine article, but it’s

a. incomplete

b. not actually the most straightforward way to do things.

So instead of editing that post, I’m going to just make a new one. I think I’ll leave the old one up for posterity’s sake, and maybe finish it eventually, but for now, this will be what I actually link for people who’re curious.

With that out of the way, here’s…

How 2 Post (v2.0!!)

So you’ve got your shiny new site, and it’s got some css, and probably just the default “hello world” message I put on the blog skeletonizer, and you’re wondering: how do I actually post on this thing?

Luckily, it’s pretty simple. There’s not nearly as much of a learning curve as you’d think.

The first thing you’re going to do, is go to the repository for your site. It will live at https://github.com/YOUR-USER-NAME/YOUR-USER-NAME.github.io.

Here’s what it should look like:

Now, you’re going to go into the _posts folder/directory. You can do this by clicking on it. I have highlighted it below:

This folder contains the markdown files that github and jekyll will use to turn into posts. What we’re going to be doing is adding a new one. To do this, click on “add file” in the top right (highlighted in the screenshot below).

Once you click on this, click on the option that says “create new file.” A form like the one in the screenshot below will pop up.

Type the name of the file you want to make in the top box, which will say “Name your file…” Jekyll does have some pretty strict rules for you you need to name your post files. Basically, you need them to have the date, the name of your post, and the “.md” file extension, in that order.

Here’s a template:

YYYY-MM-DD-name-of-my-post.md

You need to type the date in this specific format or it will either be assigned to the wrong day, or github won’t know what do with it, and won’t be able to publish your post.

For example, the name of this file is 2023-09-30-how-2-post-2.md. It’s alright to have dashes instead of spaces in the name of your file, even in the title of your post. When the title shows up on your site, the dashes will be replaced with spaces.

Now that your file has been named, you need to add the front matter to the file that’s going to become your post. This is basically how you tell github that this file is supposed to be a post, and who wrote it.

Here’s the format:

---

layout: post

author: YOUR-NAME

---

You do need the three hyphens before and after the layout and option sections. You also should replace “YOUR-NAME” with your actual name/username/pseudonym–otherwise, your post will just be credited, literally, to YOUR-NAME.

Here’s what the front matter looks like for this post:

---

layout: post

author: mossbeasts

---

As you can see, I don’t have a section with the date or the title of the post. That’s okay! You don’t need one, since they’re in the name of your file.

Once you’ve added the front matter, it’s time for the fun part: writing your post!

You can do this basically how you would in any text document - whether it’s a txt file, a Microsoft Word document, or a LibreOffice document.

There’s just one difference: if you want fancy things like italics, bold, or even bold italics (or links or headings), you need to use markdown formatting to tell github what you want to be bold or in italics. Lucky for you, markdown format is very simple to use, and easy to learn. It’s basically just learning a few new punctuation marks!

Here’s how to do it:

The effect	How to do it	What it looks like
Italics	*italics* or _italics_	italics
Bold	**bold**	bold
A link	[example link](https://example.com)	example link

The other things I often find myself using are headings and lists.

To create a heading, just put a hastag before the line that you want to be a heading.

For example, if I want this text to be in heading 1, I would write it like this:

# This will be in heading 1

and it will show up like this:

This will be in heading 1

If I want it to be in heading 2, I would just put two hashtags:

## heading 2

heading 2

Note: It’s important to make sure that you have a space after the hashtags in your heading. You don’t want to write #Heading 1 instead of # Heading 1.

To create a list, you can use either hyphens (this guy: “-“), or numbers with a period (like this: “1.”) after each paragraph that should be in the list.

For example, this:

1. One

2. Two

3. Three

will show up as this:

1. One

2. Two

3. Three

and this:

- one

- two

- three

will show up like this:

• one

• two

• three

Tip: Did you see how I included a blank line after each paragraph, even my headings and list items? It’s important to space your paragraphs like this in markdown, because otherwise jekyll won’t know what to do with them.

Something written

like

this

Will show up:

like this

while something written

like

this

will show up

like

this

back to how to post

Now that you’ve got your post all written out in markdown, it’s time to publish it! To do this, you’re going to click the button that says commit changes. It’s green.

A little box is going to pop up asking if you want to add an extended description of your commit. You don’t need to. You also want to make sure that “commit directly to the main branch” is selected.

Then, just click commit changes again, and you’re done!

You’ll be able to see the file you’ve added in your list of posts, and in a few minutes, it will show up on your website as well!

Edit: okay, that’s uh, not the post I show writing in the screenshots. But you get the idea.

Congradulations! You’ve just posted!

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.