Start Using GitHub to Publish Articles on Hashnode

Did you know that Hashnode has had a feature called "GitHub as Source" for some time now? It was available only to individual publications (personal blogs) and under a feature flag. Recently, we did a major revamp of the feature and are now supporting team publications as well. Excited to share that we shipped some significant improvements too!

Although, only a few of our users had requested sourcing posts from GitHub, the motivation behind this feature was to introduce and try out sourcing from GitHub. And maybe even extend it to a few other areas via our public API (a newer and better version will soon be launched)! Very shortly, you will be able to do all the things that our platform's editor has to offer via GitHub as a source feature.

In this article, we will explore the feature and learn more on how to publish articles from GitHub. 🙌

Dashboard details

Before starting, we have set up a template repository containing an example markdown file to make things easier. You can clone it and use the cloned repo as your source in the later steps. Link to template repository.

Installation

Head over to your publication dashboard's Integrations tab. If you scroll down, you should see the "Publish articles from GitHub" section.

Click on the "Connect Hashnode App on GitHub" button. It will take you to our app page on GitHub. Click on the install button to proceed.

Now, select the organization and ensure you have proper permission to do this. You should either be the organization's owner or have an admin role for the repository you want to select.

Once you select the appropriate organization, you will be asked to choose the repository to install this app on.

With the above step, you have two options. You can either authorize the Hashnode app for multiple repositories or select only the specific repository you want to install. Usually, people prefer the latter.

Don't worry if you accidentally selected "All repositories" and clicked on the "Install & Authorize button." We will let you choose one in later stages.

Once you click the "Install & Authorize" button on GitHub, you will be taken back to Hashnode. Depending on the number of repositories you selected in the previous step, you will be shown a list of selected repositories or the name of the repository you selected along with the publication on which this will be installed.

(If you have selected multiple repositories, you will see a dropdown with the list of those chosen repositories.)

If everything looks well and good, you can proceed, and if the installation is successful, you will see a green toast at the right bottom corner.

Publishing articles

Now that the installation is complete, you should see an updated "Publish articles from GitHub" section.

With links to instructions on How it works (1), logs (2) (you will know more about it in the later section of the article), and a helper template repository (3) to get you started quickly.

Suppose you skipped cloning the template repository at the beginning of this article and used your repo instead. You can click "Start by cloning our template repository" and check out some detailed instructions in the repo's README.

You can also use the example-post.md file and duplicate it in your repo (which you authorized in Hashnode's app).

You can use GitHub's dashboard to create and commit a new file or use your usual local flow and push it to the repo. For this article's sake, I will use GitHub's dashboard to create and commit an article.

While using the example-post template, make sure:

• You have the file name ending with the proper .md format. We only support markdown files
• You have the appropriate domain (your publication URL, both subdomain on hashnode.dev and custom domain will work)
• Appropriate comma-separated tag slugs. You can find the full list of tags here

For detailed instructions, check out the README file of the template repository or the GitHub as source logs in your publication dashboard.

As soon as you commit a new file and if all the front matter of the markdown file is OK, your article will be published on your blog.

You should also see a new log like the one below in your logs section of the publication dashboard.

There are different types of logs for errors, missing fields, etc.

Now, if you go to the articles section of your dashboard, you will see that the articles you created using GitHub are tagged as "Sourced from GitHub."

Important note

One thing you will have to be aware of is that the articles that are created using "GitHub as Source" are not editable on the platform. You will have to update it using GitHub itself.

You can even use the "publishAs" attribute in your markdown front matter if you are on a team publication. Make sure the "publishAs" is the username which is already a member of the publication, otherwise you will not be allowed to publish.

There is a growing list of parameters that we are supporting in the markdown front matter. For the updated list, you can watch our support website or the Template repository.

Debugging

At any given point, if you are stuck in between, check out the logs. If you don't see any log, ensure the file name is proper and has a .md extension. Check if the blog domain is correct. If nothing works out, then go through the instructions list in the logs section.

You can always reach out to us via the intercom chat widget at the right bottom corner of every page of hashnode.com (you should be logged in to access it).

---

Thanks for reading! Please leave any comments or feedback below - this really helps us improve! 👇‍