The Design Guide

A simple design guide for everything related to Git and Github (especially Markdown)

This project is here to help you get inspired and learn how to make your README files and other project content look better. It gives you ideas and tips that can be really helpful, but you don't have to do everything exactly as it says.

Feel free to:

• Use this guide for your own projects
• Contribute to this project if you see something that can be improved or added

• Markdown

  • Headings
  • Text Formatting
  • Colors
  • Links
  • Lists
  • TODO Lists
  • Alerts (Special blockquotes)
  • Emojis
  • HTML
  • HTML Symbols and Entities

• Repository README

  • Structure
  • Badges

• Profile README

• Commits

  • Commit Messages
  • Emojis in Commit Messages

Here is the source of the following information

  
# A first-level heading

## A second-level heading

### A third-level heading

A first-level heading

A second-level heading

A third-level heading

  
**This is bold text**
This is bold text


_This text is italicized_
This text is italicized


~~This was mistaken text~~
This was mistaken text  

  
> Text that is a quote
Text that is a quote

Note
Color visualization is supported only in Issues, Pull Requests and Discussions.

`#0969DA`
`rgb(9, 105, 218)`
`hsl(212, 92%, 45%)`
 

  
[This is a link](https://github.com/max1mde/DesignGuide)
This is a link

[License of this project](LICENSE)
License of this project
Relative link

    
- First list item
- Second list item
- Third list item

• First list item
• Second list item
• Third list item

    
- [x] A todo which is done
- [ ] An issue https://github.com/max1mde/HologramAPI/issues/1

• A todo which is done
• An issue max1mde/HologramAPI#1

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

Here you can find a list of all emojies

You might have already seen that you can use HTML tags, like the <a> or <img> tags in a Markdown file.
But there are more tags you can use.
You will probably find a tag for every Markdown feature and even more tags.
HTML tags give you more possibilities and control.

For example, you can center any element by surrounding it with this div.

<div align="center">
  <!--- elements to center -->
</div>

Maybe you want to change the size of an image

<img src="image.png" width="200">

Or create a collapsible section

<details>
<summary>The title</summary>
  <p>And the hidden content</p>
</details>

Which would look like this:

When writing HTML, you might want to display certain symbols, like <, >, or & without having them interpreted as HTML tags. For this, you can use HTML entities, which are special codes that represent characters.

HTML entities always start with an & and end with a ;. Here are some common ones:

• < — Represents < (less-than symbol)
• > — Represents > (greater-than symbol)
• & — Represents & (ampersand)
• " — Represents " (double quote)
• ' — Represents ' (single quote)

These entities are especially useful in documentation or README files where you might want to show code snippets that include HTML tags without them being interpreted as actual HTML.

For example, if you want to display the text <div align="center"> without it being treated as an HTML tag, you would write:

<div align="center">

Other useful HTML entities:

• © — © symbol
• ® — ® symbol
• € — € symbol
• ¥ — ¥ symbol
• ™ — ™ symbol

• Badges  (optional)
• Title
• Description
• Banner/Showcase of the project  (optional)
• Table of Contents (optional but good for big readme's)
• Installation
• Usage
• How to Contribute, Licence, Credits etc  (optional)

Badges display important details about a project, such as version, license, downloads, and ratings. These badges can be either static or dynamic and also include symbols. These small graphical elements are typically found at the top of your readme and are provided by various services like shields.io.

You can use the html image tag to display a badge:

<img alt="GitHub license" src="https://img.shields.io/github/license/max1mde/DesignGuide">

You can also make them clickable by enclosing the <img> element within an <a> element, like this:

<a href="https://github.com/max1mde/DesignGuide/blob/main/LICENSE">
  <img alt="GitHub license" src="https://img.shields.io/github/license/max1mde/DesignGuide">
</a>

Nothing here yet. You can change this by opening a pull request and contributing to this project

Writing clear commit messages is crucial for a clean Git history

• Keep messages concise.
• Use imperative mood.
• Separate subject from body.
• Reference issues if applicable.
• Use emojis wisely.

Emojis enhance commit messages, conveying change nature visually. They provide a quick understanding.

Here's how you can use them for different changes:

• 🐛 Fixing a bug
• 📝 Updating code/documentation
• 🚀 Introducing a new feature
• 🔒 Fixing a security issue
• 🧹 Refactoring code
• 📈 Improving performance
• 🗑️ Removing code
• ↗️ Upgrading dependencies
• ↙️ Downgrading dependencies
• 📋 Adding comments
• ➕ Adding new code

For more examples of what emojies you can use in your commit messages, check out this website.