An AppEngine app to embed files from a github repository like a gist - robertkrimen/gist-it.

• Gist Markdown Method
• Git Markdown Book
• Gist Markdown Emoji
• Git Markdown
• Gist Markdown Image
• Gist Markdown Table

1. Task Lists are also available in Gist comments and in Gist Markdown files. Here’s an example of how you can use syntax highlighting with GitHub.
2. Gist Markdown Cheatsheet. GitHub Gist: instantly share code, notes, and snippets.

IntroCave Updates

It would be really meta of me to take a screenshot of this text editor and use it as my header graphic.

People are good at some tasks. Computers are good at other tasks. I haven't been shy about my love of automating routine tasks so I don't have to do as much, but one area that has remained pretty high-touch has been writing blog posts. I'm not using WordPress or any kind of 3rd-party blog hosting—there's just a plain old normal Laravel blog model that stores the HTML you're reading now. When I first started writing these posts, the IntroCave admin panel had a WYSIWYG (What You See Is What You Get) blog composer similar to what you might see in a WordPress admin panel. After giving the blog a visual refresh, though, it was tedious to constantly switch back and forth from the HTML view to the code view to add the proper CSS tags. I ditched the fancy editor for a plain text box, instead opting to just write all my posts straight in HTML.

Gist Markdown Method

I'm being too kind to WYSIWYG editors, though.

I've hated WYSIWYG editors ever since my very first programming job. I was tasked with writing a wiki editor using Adobe's Flex. It suuuuuuucked, and I've hated them ever since. It's not all their fault, though—the problem is how I write.

Write the Post

I don't use a word processor. I don't want to think about formatting. I don't want to think about header graphics. I don't want to think about font-sizes or header-sizes. I just want to write words, and that means just using a dumb simple text editor. I can save my drafts to disk without worrying about refreshing or losing state, I don't have to think about formatting, and I can just work on the content of the article without having to think about anything else.

It would take a tremendous amount of code for a textarea inside of a web browser to have the same level of usability and reliability as a simple text editor. Hotkeys do weird things, sometimes the form's CSRF token expires if you leave it open too long, sometimes they try to do smart autocorrect bullshit that takes you out of your flow. Writing is hard enough without your tools getting in the way, so I prefer to use a tool that's just designed to extract words out of me.

Edit/Format/Publish the Post

Once a post is done, I have to format it for the blog. This mostly means wrapping paragraphs in the right tags, adding links, adding headers, and stubbing in a few images. I add a new feature or widget to posts every now and then, but for the most part, I'm working with a very very small number of types of styled elements. Going in and manually adding CSS classes using the WYSIWYG editor was too cumbersome.

Up until now, I would just switch over from plaintext to HTML. It's not so hard to go copy/paste in a handful of paragraph tags and CSS classes, and it gives me the flexibility to add special formatting if I want to throw a new kind of list in the middle of a post. Tedious: yes. But less tedious than editing in-browser, even though I have to copy/paste my markup into a form field every time I want to preview changes.

This can be a fairly tedious process depending on the ratio of words to other stuff, and it's one of the reasons I decided that outsourcing blog content wasn't worth it. A lot of the content marketing services are set up to publish for you in WordPress, but it would be too much to ask for them to exactly format their posts using the markup that makes them look normal on my blog.

The final step in my editing process is to pass the text through a spelling/grammar checker. I'm currently using Grammarly for this, and it usually catches at least a half-dozen small mistakes.

Enter Markdown

It's hardly revolutionary to say that Markdown solves this problem for me. It's been around for 15 years, pretty much for this exact reason. The reason I didn't switch earlier was honestly just misplaced fear. My writing goes through three phases: WRITE -> EDIT -> PUBLISH. Even though the majority of my writing happens in the writing phase, I do tend to tweak a lot in the editing phase.

I wanted to use a tool to convert my text draft into an HTML draft automagically, but I also knew I would need to hand-edit that HTML markup to add the proper CSS classes. You can't easily go back to the text version once you've made changes to your generated file, as those changes are highly at risk of getting overwritten if you run your processor again. In an ideal world, your generated files are never touched at all—you just publish the output and stick to editing the text versions.

I knew Markdown could do most of that, but I assumed it would be a pain in the ass to augment the generated HTML syntax. Markdown has a bit of a reputation (largely owing to its original author, John Gruber) for being opinionated: i.e. do it our way or don't bother. When I finally sat down to write my own Markdown processor, I realized there was no need. The Red Carpet gem gives you pretty nice callbacks to muck with the output however you want. The whole thing is tiny and should save me at least 30 minutes on every blog post I write. You can see my tiny processing script below.

The thing I like best about this particular gem is that you can mix and match HTML in with your Markdown syntax pretty easily, whether it's a YouTube embed or a Github gist like below. I can never remember the syntax for a link in Markdown, so I just write HTML tags like I'm used to and the processor doesn't whine at me.

Besides saving me time with each blog post, having a Markdown processor also opens the door to hiring writers again. While asking for hand-formatted HTML is a tall ask, requesting an article in Markdown syntax is reasonable. There's always going to be a little bit of work uploading images and fixing paths, but it seems a lot less tedious than it was before.

Moral of the story: keep working on your tools and processes. It's worth it!

If you're curious what my rendering script looks like, I've embedded it below. I could probably bake the Markdown processing step into my web server instead of running a script in the console, but I like having the flexibility to tweak it before it goes in the database if I ever run into something that Markdown can't handle.

IntroCave is a one-person-show operated by Will Hankinson, but it's not 100% accurate to say every word is written by me. Some articles were live on the site when I took over. I hire writers from time to time to work on specific articles. Todoist app. People keep asking me to do guest posts, but I haven't actually seen any relevant submissions yet. 'IntroCave staff' might make a better by-line, but currently that's just me. I've been building digital things for 10+ years now, and some of my favorite projects are posted over at my personal website if you want to take a look!

YouTube Video Notes: How Much I Made From 10 Million Views in 30 Days

YouTube

IntroCave Interview on IndieHackers

IntroCave Updates

• We use a markdown editor that uses Jekyll front matter.
• Most of the time, you can write inline HTML directly into your posts.
• We support native Liquid tags and created some fun custom ones, too! Trying embedding a Tweet or GitHub issue in your post.
• Links to unpublished posts are shareable for feedback/review.
• When you're ready to publish, set the published variable to true.

We have two editor versions. If you'd prefer to edit title and tags etc. as separate fields, switch to the 'rich + markdown' option in /settings/customization. Otherwise, continue:

Front Matter

Custom variables set for each post, located between the triple-dashed lines in your editor. Here is a list of possibilities:

• title: the title of your article
• published: boolean that determines whether or not your article is published
• description: description area in Twitter cards and open graph cards
• tags: max of four tags, needs to be comma-separated
• canonical_url: link for the canonical version of the content
• cover_image: cover image for post, accepts a URL.
  The best size is 1000 x 420.
• series: post series name.

✍ Markdown Basics

Below are some examples of commonly used markdown syntax. If you want to dive deeper, check out this cheat sheet.

Bold & Italic

Italics: *asterisks* or _underscores_

Bold: **double asterisks** or __double underscores__

Links

I'm an inline link: [I'm an inline link](put-link-here)

Anchored links (For things like a Table of Contents)

Inline Images

When adding GIFs to posts and comments, please note that there is a limit of 200 megapixels per frame/page.

Headers

Add a header to your post with this syntax:

Two '#'s for a h2 header

Six '#'s for a h6 header

Author Notes/Comments

Add some hidden notes/comments to your article with this syntax:

🌊 Liquid Tags

We support native Liquid tags in our editor, but have created our own custom tags listed below:

The Community Club Article/Post Embed

All you need is the full link of the article:

{% link https://the.community.club/kazz/boost-your-productivity-using-markdown-1be %}

You can also use the slug like this:

{% link kazz/boost-your-productivity-using-markdown-1be %}

You can also use the alias post instead of link like this: Access 365 owa.

{% post https://the.community.club/kazz/boost-your-productivity-using-markdown-1be %}

or this:

{% post kazz/boost-your-productivity-using-markdown-1be %}

The Community Club User Embed

All you need is the The Community Club username:

{% user jess %}

The Community Club Tag Embed

All you need is the tag name:

{% tag git %}

The Community Club Comment Embed

All you need is the ID at the end of a comment URL. To get the comment link, click either the timestamp or the menu button in the top right corner on a comment and then click 'Permalink'. Here's an example:

{% comment 2d1a %}

The Community Club Podcast Episode Embed

All you need is the full link of the podcast episode:

{% podcast https://the.community.club/basecspodcast/s2e2--queues-irl %}

The Community Club Listing Embed

All you need is the full link of the listing:

{% listing https://the.community.club/listings/collabs/dev-is-open-source-823 %}

You can also use the category and slug like this:

{% listing collabs/dev-is-open-source-823 %}

Note: Expired listings will raise an error. Make sure the listing is published or recently bumped.

Details Embed

You can embed a details HTML element by using details, spoiler, or collapsible. The summary will be what the dropdown title displays. The content will be the text hidden behind the dropdown. This is great for when you want to hide text (i.e. answers to questions) behind a user action/intent (i.e. a click).

{% details summary %} content {% enddetails %}

{% spoiler summary %} content {% endspoiler %}

{% collapsible summary %} content {% endcollapsible %}

Twitter Embed

Using the Twitter Liquid tag will allow the tweet to pre-render from the server, providing your reader with a better experience. All you need is the tweet id from the url.

{% twitter 834439977220112384 %}

Twitter Timeline

Using the Twitter Timeline Liquid tag will allow the Twitter Timeline to pre-render from the server. All you need is the Twitter Timeline link.

{% twitter_timeline https://twitter.com/username/timelines/834439977220112384 %}

Glitch embed

All you need is the Glitch project slug

{% glitch earthy-course %}

There are several optional attributes you can use in your tag, just add them after the id, separated by spaces.

app

Shows the app preview without the code.
{% glitch earthy-course app %}

code

Shows the code without the app preview.
{% glitch earthy-course code %}

preview-first

Swap panes: Show the app preview on the left and the code on the right.
{% glitch earthy-course preview-first %}

no-attribution

Hides the avatar of the creator(s).
{% glitch earthy-course no-attribution %}

no-files

Hides the file browser.
{% glitch earthy-course no-files %}

file

Lets you choose which file to display in the code panel. Defaults to index.html.
{% glitch earthy-course file=script.js %}

GitHub Repo Embed

All you need is the GitHub username and repo:

{% github forem/forem %}

no-readme

You can add a no-readme option to your GitHub tag to hide the readme file from the preview.
{% github forem/forem no-readme %}

GitHub Issue, Pull request or Comment Embed

Git Markdown Book

All you need is the GitHub issue, PR or comment URL:

{% github https://github.com/forem/forem/issues/9 %}

GitHub Gist Embed

All you need is the gist link:

{% gist https://gist.github.com/CristinaSolana/1885435 %}

Single File Embed

You can choose to embed a single gist file.
{% gist https://gist.github.com/CristinaSolana/1885435 file=gistfile1.md %}

Specific Version Embed

You can choose to embed a specific version of a gist file. All you need the link and the commit hash for that specific version.
The format is {% gist [gist-link]/[commit-hash] %}
e.g.
{% gist https://gist.github.com/suntong/3a31faf8129d3d7a380122d5a6d48ff6/f77d01e82defbf736ebf4879a812cf9c916a9252 %}

Specific Version File Embed

You can choose to embed a specific version of a gist file. All you need the link, the filename and the commit hash for that specific version .
The format is {% gist [gist-link]/[commit-hash] file=[filename] %}
e.g.
{% gist https://gist.github.com/suntong/3a31faf8129d3d7a380122d5a6d48ff6/f77d01e82defbf736ebf4879a812cf9c916a9252 file=Images.tmpl %}

GitPitch Embed

All you need is the GitPitch link:

{% gitpitch https://gitpitch.com/gitpitch/in-60-seconds %}

Video Embed

All you need is the id from the URL.

• YouTube:{% youtube dQw4w9WgXcQ %}
• Vimeo:{% vimeo 193110695 %}
• Twitch:{% twitch ClumsyPrettiestOilLitFam %}

Medium Embed

Just enter the full URL of the Medium article you are trying to embed.

{% medium https://medium.com/s/story/boba-science-how-can-i-drink-a-bubble-tea-to-ensure-that-i-dont-finish-the-tea-before-the-bobas-7fc5fd0e442d %}

SlideShare Embed

All you need is the SlideShare key:

{% slideshare rdOzN9kr1yK5eE %}

CodePen Embed

All you need is the full CodePen link, ending in the pen ID code, as follows:

Gist Markdown Emoji

{% codepen https://codepen.io/twhite96/pen/XKqrJX %}

default-tab

Add default-tab parameter to your CodePen embed tag. Default to result
{% codepen https://codepen.io/twhite96/pen/XKqrJX default-tab=js,result %}

Kotlin Playground

To create a runnable kotlin snippet, create a Kotlin Snippet at https://play.kotlinlang.org

Go to Share dialog and copy the full link from the Medium tab. Use it as follows:

{% kotlin https://pl.kotl.in/owreUFFUG?theme=darcula&from=3&to=6&readOnly=true %}

RunKit Embed

Git Markdown

Sunny hostin i am these truths. Put executable code within a runkit liquid block, as follows:

KaTeX Embed

Place your mathematical expression within a KaTeX liquid block, as follows:

To render KaTeX inline add the 'inline' option:

Stackblitz Embed

All you need is the ID of the Stackblitz:

{% stackblitz ball-demo %}

Default view

You can change the default view, the options are both, preview, editor. Defaults to both
{% stackblitz ball-demo view=preview %}

Default file

You can change the default file you want your embed to point to
{% stackblitz ball-demo file=style.css %}

CodeSandbox Embed

All you need is the ID of the Sandbox:

{% codesandbox ppxnl191zx %}

Of CodeSandbox's many optional attributes, the following are supported by using them in your tag, just add them after the id, separated by spaces.

initialpath

Which url to initially load in address bar.
{% codesandbox ppxnl191zx initialpath=/initial/load/path %}

module

Which module to open by default.
{% codesandbox ppxnl191zx module=/path/to/module %}

runonclick

Delays when code is ran if 1
{% codesandbox ppxnl191zx runonclick=1 %}

JSFiddle Embed

All you need is the full JSFiddle link, ending in the fiddle ID code, as follows:

{% jsfiddle https://jsfiddle.net/link2twenty/v2kx9jcd %}

Gist Markdown Image

Custom tabs

You can add a custom tab order to you JSFiddle embed tag. Defaults to js,html,css,result
{% jsfiddle https://jsfiddle.net/webdevem/Q8KVC result,html,css %}

JSitor Liquid Tag

To use JSitor liquid tag you can use the JSitor full link, with or without the parameters

{% jsitor https://jsitor.com/embed/B7FQ5tHbY %}
{% jsitor https://jsitor.com/embed/B7FQ5tHbY?html&js&css&result&light %}

Other options to use JSitor liquid tag is just by its ID, you can add it with or without the parameters

{% jsitor B7FQ5tHbY %}
{% jsitor B7FQ5tHbY?html&js&css&result&light %}

repl.it Embed

All you need is the URL after the domain name:

{% replit @WigWog/PositiveFineOpensource %}

Stackery Embed

Visualize your AWS Serverless Application Model templates with Stackery's visualizer embed

All you need is the repository owner, repository name, and branch that you would like visualized

{% stackery deeheber lambda-layer-example master %}

The repository must be a public GitHub repository and have a valid AWS SAM template in the project root titled template.yaml

Next Tech Embed

All you need is the share URL for your sandbox. You can get the share URL by clicking the 'Share' button in the top right when the sandbox is open.

{% nexttech https://nt.dev/s/6ba1fffbd09e %}

Instagram Embed

All you need is the Instagram post id from the URL:

{% instagram BXgGcAUjM39 %}

Speakerdeck Tag

All you need is the link. For example:
https://diy.stackexchange.com/a/170185

• The answer ID is: 170185
• The site is diy

Wikipedia Embed

Enter the full URL of the Wikipedia article you want to embed, with or without the anchor.

{% wikipedia https://en.wikipedia.org/wiki/Wikipedia %}
{% wikipedia https://en.wikipedia.org/wiki/Wikipedia#Diversity %}

Asciinema Embed

All you need is an Asciinema id or URL:

{% asciinema 239367 %}{% asciinema https://asciinema.org/a/239367 %}

Reddit Tag

Enter the full URL of the post you want to embed

Parsing Liquid Tags as a Code Example

To parse Liquid tags as code, simply wrap it with a single backtick or triple backticks.

`{% mytag %}{{ site.SOMETHING }}{% endmytag %}`

One specific edge case is with using the raw tag. To properly escape it, use this format:

`{% raw %}{{site.SOMETHING }} {% ``endraw`` %}`

Common Gotchas

Gist Markdown Table

Lists are written just like any other Markdown editor. If you're adding an image in between numbered list, though, be sure to tab the image, otherwise it'll restart the number of the list. Here's an example of what to do:

Here's the Markdown cheatsheet again for reference.

Happy posting! 📝