Automate Gist Creation From Markdown File Using Python
Published: 2021-05-11 12:33:19

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 Intro

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.

## Why to use gist?

* 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.


![Gist Share](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gjgbl522f6qn80nlud9k.png)

# Why use gist in a blog?

My current workflow for blogging is as follows:

1. Use Jupyter notebook to write the blog.
2. Download the notebook as markdown file.
3. Make edits to markdown file before posting to platforms like [Medium](https://6aravind.medium.com) & [Dev to](https://dev.to/6aravind)

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

|<center> Medium </center>| <center> Gist </center> |
|:-:|:-:|
|![Medium](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/llo6oottctvi4cqfcuzz.png)|![Gist](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ep0ep4wuolfadfemlndk.png)|

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).

# Gist Creation From Markdown File

The goal is to create a gist for the markdown file where every code snippet will be a separate file.


1. First we will download the token for gist creation like mentioned in [this post](https://www.liquidweb.com/kb/little-known-ways-to-utilize-github-gists/) and store it in a file named - *create_gist_token.txt*


	{% gist https://gist.github.com/6aravind/e51d97ff0e99af896f5b0571c7952c7d file=Read_Gist_Creation_Token.py %}
	
	

2. 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](https://docs.python.org/3/library/re.html#re.S) makes sure that the matching includes newline as well


	{% gist https://gist.github.com/6aravind/e51d97ff0e99af896f5b0571c7952c7d file=Read_Markdown_File_and_Get_Code_Snippets.py %}
	
	

3. 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.


	{% gist https://gist.github.com/6aravind/e51d97ff0e99af896f5b0571c7952c7d file=Get_the_first_comment_from_code_snippet.py %}
	
	

4. 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.


	{% gist https://gist.github.com/6aravind/e51d97ff0e99af896f5b0571c7952c7d file=Setup_data_and_make_api_call.py %}
	
	

5. 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. 


	{% gist https://gist.github.com/6aravind/e51d97ff0e99af896f5b0571c7952c7d file=Gist_Embedding.py %}
	
	

6. 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.


	{% gist https://gist.github.com/6aravind/e51d97ff0e99af896f5b0571c7952c7d file=Replace_the_code_blocks_with_corresponding_gist_in_the_Markdown_file.py %}
	
	
7. Rewiring the script to make it easier to run from command line.


	{% gist https://gist.github.com/6aravind/e51d97ff0e99af896f5b0571c7952c7d file=Gist_Creation_From_Markdown_File.py %}
	
	
# Takeaway

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](https://twitter.com/6aravind) or comments on your thoughts about this post.