I spend quite some time browsing GitHub every day. I use the Trending section to filter the projects by language. I then proceed to explore each project by reading the README and maybe browsing the code, some issues and pull requests to see how the project is being maintained. The community is creating an immense number of projects and it’s one of the things I like the most about the Swift community.
By browsing new open source projects almost every day, I noticed that many of them don’t take full advantage of some cool Markdown features. The README is the first thing that people see when approaching your repository. If you want to attract users, contributors or simply interest, it is crucial to give them the best possible first impression. In this post, I would like to show some tips and tricks to take your README to the next level.
This post is focused on Swift but many of the following points can be applied to any other language.
Syntax Highlighting
This is a very simple feature that you can add to your code snippets. GitHub uses Linguist to do the syntax highlighting and automatically set your repo language. Just add the language name after triple backticks.
```swift
print("Hey")
```
The result will be much easier to read and understand.
Spoiler Effect
Markdown doesn’t provide a lot of features to make text interactive but we can use some supported HTML tags given that GitHub uses what’s called “GitHub Flavored Markdown”. I recently discovered this feature after using fastlane which heavily uses it to make submitting and browsing issues a joy.
It allows to collapse text inside a section. You can then click on the arrow to reveal the full content. This is especially useful to keep the text short to read but still preserve the information for those who need are interested.
There are a lot of use cases. For example you could offer both Swift and Objective-C example code for your library or show multiple methods of integration with different dependency managers. This is what the HTML code could look like:
<details>
<summary>CocoaPods</summary>
Add the following line to your `Podfile`:
```ruby
pod 'YourAwesomeLibrary'
```
</details>
<details>
<summary>Carthage</summary>
Add the following line to your `Cartfile`:
```swift
github "YourUsername/YourAwesomeLibrary"
```
</details>
<details>
<summary>Manual</summary>
Clone the repo and drag and drop the files into your project.
</details>
This is what it looks like in action.
CocoaPods
Add the following line to your `Podfile`:
```ruby
pod 'YourAwesomeLibrary'
```
Carthage
Add the following line to your `Cartfile`:
```swift
github "YourUsername/YourAwesomeLibrary"
```
Manual
Clone the repo and drag and drop the files into your project.
Demo Image or Video
An image is worth a thousand words, you know that. If I don’t see a demo image, GIF or video for a project, chances are high that I will leave without trying it out. You should try as much as possible to grab the user attention with a concise image or GIF to show off what your project does. A great example is an animation library called Hero. It was released a few weeks ago and the developer published a Youtube video showing all the power of the library. The video went viral in my timeline and that brought traffic to the project which today has over 5K ⭐️.
Unfortunately Markdown doesn’t support embedded videos, so your options are:
- If the video isn’t too long, create a GIF out of it and add it to the repo.
- Display an image with a link to the video.
- Simply mention the video and add a link somewhere in your README.
I usually try to go with the first option as it doesn’t require the user to switch context to watch the video.
Links Grouping
This was a very new addition that I didn’t know was supported. If you find yourself writing more than once the same link in your Markdown file, you can create an alias so that you can define it only once.
Find me on [Twitter][my twitter].
If you need support, [tweet me][my twitter].
[my twitter]: https://www.twitter.com/BalestraPatrick
This pattern makes it really easy to change a link later on without having to go through the whole file to make sure every link was changed.
Coding Guidelines
Try to stick to a single coding style for your whole project. I recommend reading the Swift Style Guide so that other developers can see your coding style in case they would like to contribute.
Structure
Try to structure your README in a easy way to navigate. Write your first version and then come back after a few days to make sure it’s understandable for someone who has never seen your project.
To insert a line to divide sections use 5 consecutive “-” for example. Take a look at the Markdown syntax in this guide.
Code of Conduct and Contributing Guidelines
Having a code of conduct is always a nice addition if you plan to scale your library to the next level. Contributing guidelines are also useful for new developers who would like to contribute to your project. A simple list of required step to open an issue or pull request is a very nice idea. Check out the GitHub documentation to learn what you can do to make it easier for people to contribute to your project.
Contact Information
Don’t forget to mention who is part of the project, it’s always nice to see who is behind any cool idea on the internet. 😎
Please let me know of any tips you think are useful for improving a README on Twitter.