Markdown's code block is great for writing code snippets. However, when you try to publish or share it via blogging platform there are some shortcomings. Gist can help to bridge the gap. Gist makes your blog look better & easier to maintain. In this post, Let us see how automated gist creation can improve your technical blogging experience.
Gist is a GitHub repository where you can store & share code/data with others. A single gist can store multiple files. Syntax highlighting is supported based on the file extension type, so be careful when you name the file. Gists can be public or secret. Do note that secret gists aren't private, meaning anyone with the URL would be able to view the code/data.
Supports GitHub repository functionalities like version control, fork & clone.
Ability to subscribe, star and comment makes gist easy to collaborate with others.
Gist can be shared in multiple ways without any dependency or installation.
My current workflow for blogging is as follows:
- Use Jupyter notebook to write the blog.
- Download the notebook as markdown file.
- Make edits to markdown file before posting to platforms like Medium & Dev to
There are many manual processes involved in step 3, which I'm planning to address in the next few weeks. My biggest concern right now is how the code snippet looks in different platforms. To be more specific:
- No easy way to make changes to code snippets after publishing
- Medium loses syntax highlighting
- Unable to highlight specific lines in a long code snippet in both the platforms
Gist helps to solve all these issues. Also as a bonus, All code snippets from the same blog can be grouped together via gist. This makes it easier to refer/access (if needed).
The goal is to create a gist for the markdown file where every code snippet will be a separate file.
First we will download the token for gist creation like mentioned in this post and store it in a file named - create_gist_token.txt
We can read the markdown file using python and use regular expression to find all the code blocks. Code block for python is created by wrapping the code between `` in the markdown file. The flag re.S makes sure that the matching includes newline as well
As mentioned earlier, each code snippet is going to be a separate file in a gist, so we need a name for each one. To keep it simple, we will take the first comment as the name of the file.
The description of the gist will be the first header of the markdown file. Typically, this will be the name of the blog, so it should be sufficient. Now we can put all the data together and make the API call.
As Dev to supports liquid text we need special formatting for gist embedding when compared to Medium. In both the platforms, we need to specify the file so that the entire gist is not displayed.
Loop through all the uploaded files and replace them with corresponding gist embeddings in the markdown file. I have included the embeddings for both the platforms, feel free to modify it as per your needs.
Rewiring the script to make it easier to run from command line.
Gist is quite useful and addresses many of the pet peeves in blogging. We have managed to put together a python script which can reduce the manual effort required in publishing a blog. Feel free to reach out to me via Twitter or comments on your thoughts about this post.