Notes on some (non-obvious) Gist behaviors, and how I plan to use them.

How the title works

The title is probably the first thing someone will see of the gist, so it's kind of important. Put simply: the title is the filename (including extension) of the "first" file in the Gist - first after GitHub re-orders them, at least.

So, how does GitHub re-order the files? Well... alphabetically, sort of.

There are a few tricky parts, like where it puts symbols, in relation to each other and in relation to the modern English alphabet. Another tricky part is how it orders capital letters. Additionally, when editing files online, the GitHub UI might remove prepended spaces in titles - although you can manually commit and push files with the "correct" name. The final tricky part is that GitHub has changed, and might change again, how it does the re-ordering: see comments in this StackOverflow post for solutions that once worked, but don't anymore.

Here are some rules, as of whenever I wrote this:

Symbols should be considered random: # comes before a comes before ~.
Uppercase letters come just before their lowercase counterparts, so A comes before a comes before B.
Numbers come before letters, and 0 comes before 1.

Descriptions

They appear in plain text at the top of the gist, and like a subtitle in the Discover UI. They don't support markdown.

The URL

Seems to be random.

Images

It's probably easiest to put images in markdown files by using the GitHub UI, although this will upload the image to user-images.githubusercontent.com. That's probably not an issue, it's just something to note.

You can "manually" add them to the repository locally, then push and commit them, but then they will appear on their own in the gist. If you want to include a "local" image in a markdown file, good luck - I couldn't figure out how to make the relative link work.

Secret gists

The name is a bit misleading, because they aren't really very secret, they just don't appear in searches. Anyone with the URL can see the content. This makes sense if you think of gists as specifically being to share information.

You can convert a secret gist into a public gist, but not vice versa.

How I plan to use gists

Since gists can be commented on, I think they could be a general blog-like platform. The main content will be in markdown, with the filename like #Example_Title.md. That will make it appear at the top of the page, and be the gist title for searchability. Descriptions should be descriptive, and not be the same as the title. Most headings will be at the second level, eg ## Examples: I'll try not to worry about where the other files appear on the page, although if I really want some to appear last, I will prepend their titles with zz_. Sentences should be on separate lines in markdown files.