https://github.com/maximjsx/DesignGuide

🎨 A simple design guide for using Markdown 📄 & Github/Git 💻 in general
https://github.com/maximjsx/DesignGuide

design design-guide markdown readme readme-structure

Last synced: 10 months ago
JSON representation

🎨 A simple design guide for using Markdown 📄 & Github/Git 💻 in general

Host: GitHub
URL: https://github.com/maximjsx/DesignGuide
Owner: maximjsx
License: gpl-3.0
Created: 2023-08-14T19:08:37.000Z (almost 3 years ago)
Default Branch: main
Last Pushed: 2024-11-22T12:17:18.000Z (over 1 year ago)
Last Synced: 2025-04-06T08:14:13.827Z (about 1 year ago)
Topics: design, design-guide, markdown, readme, readme-structure
Homepage:
Size: 80.1 KB
Stars: 3
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

          


  The Design Guide

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

  

  

    

    

    

    

    

    



# About This Project

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

# Table of Contents

- [Markdown](#markdown)

  - [Headings](#headings)

  - [Text Formatting](#text-formatting)

  - [Colors](#colors)

  - [Links](#links)

  - [Lists](#lists)

  - [TODO Lists](#todo-lists)

  - [Alerts (Special blockquotes)](#alerts)

  - [Emojis](#emojis)

  - [HTML](#html)

  - [HTML Symbols and Entities](#html-symbols-and-entities)

- [Repository README](#repository-readme)

  - [Structure](#structure)

  - [Badges](#badges)

- [Profile README](#profile-readme)

- [Commits](#commits)

  - [Commit Messages](#commit-messages)

  - [Emojis in Commit Messages](#emojis-in-commit-messages)

---

# Markdown

Here is the source of the following information  

### Headings

  

# A first-level heading


## A second-level heading


### A third-level heading


A first-level heading

A second-level heading

A third-level heading



### Text formatting

  

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

  

Colors

  

> **Note**  

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


`#0969DA`

`rgb(9, 105, 218)`

`hsl(212, 92%, 45%)`
 





Links

  

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

This is a link


[License of this project](LICENSE)

License of this projectRelative link  

Lists

    

- First list item

- Second list item

- Third list item



First list item

Second list item

Third list item

    

TODO Lists

    

- [x] A todo which is done

- [ ] An issue https://github.com/max1mde/HologramAPI/issues/1


- [x] A todo which is done

- [ ] An issue https://github.com/max1mde/HologramAPI/issues/1


### Alerts

```

> [!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.

```

> [!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.

### Emojis

| icon | shortcode | icon | shortcode |

| :-: | - | :-: | - |

| 😄 | `:grinning:` | 😃 | `:smiley:` |

| 😄 | `:smile:` | 😁 | `:grin:` |

| 😆 | `:laughing:` `:satisfied:` | 😅 | `:sweat_smile:` |

| 🤣 | `:rofl:` | 😂 | `:joy:` |

| 🙂 | `:slightly_smiling_face:` | 🙃 | `:upside_down_face:` |

| 😉 | `:wink:` | 😊 | `:blush:` |

Here you can find a list of all emojies

### HTML

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:

The title

  
And the hidden content


### HTML Symbols and Entities

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 `
` without it being treated as an HTML tag, you would write:


`<div align="center">`

Other useful HTML entities:

- `©` — © symbol

- `®` — ® symbol

- `€` — € symbol

- `¥` — ¥ symbol

- `™` — ™ symbol

---

# Repository readme

Structure


• 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

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>



---

# Profile readme

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


---

# Commits

### Commit messages

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 in commit messages

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.