# Create an Excellent GitHub Profile with Markdown ## Overview ![](https://cdn-learn.adafruit.com/assets/assets/000/112/622/medium800/programming_GitHub_logo_with_mark.png?1656187481) GitHub is a web service that keeps track of code and files, designed to enable folks to collaborate on projects. Just about all of Adafruit's coding projects and hardware are hosted on GitHub. Since Adafruit publishes open source hardware and software, this works great to share the designs and also get feedback and improvements from the community. Community members can even find bugs or add new features, and submit those back to Adafruit so that _everyone_ can benefit from the effort! ![](https://cdn-learn.adafruit.com/assets/assets/000/112/621/medium800/programming_GFP_README_general_for_overview.png?1656186917) GitHub has a personal profile feature that allows you to create a profile that shows up if someone views your main GitHub page. You'll find an example [here.](https://github.com/kattni) To create a profile, you create a repository with the same name as your GitHub user ID, and add a **README.md** file to that repository. You then add the info you'd like to include using Markdown, and GitHub renders it. That's all there is to it! Right? Not exactly. How do you make a repository with a README file in it? What is Markdown? How do you know what to include in your profile? How do you use Markdown to make all of this happen? This guide has you covered. This guide will first discuss some ideas about what content you might want to include in your profile. Next, you'll learn how to create your repository and include a **README.md** file in it. You'll also learn about Markdown and how to edit the README file. You'll be introduced to some tools to assist with generating content that fits your needs and desires. Throughout the process, you'll follow along with a demonstration of creating and updating a GitHub profile. By the time you're done here, you'll be able to point folks to a wonderful GitHub profile that is both memorable and representative of you! ## Terminology Here are some interchangeable terms used in this guide. - **repository** and **repo** - The latter is short for the former; both refer to a repository. - **README** and **README.md** - The README file this guide refers to is specifically a README.md file, however, both terms are used in multiple places. - **commit** and **save** - GitHub refers to "saving" your content as "committing". Most of the time commit and committing are used, however you may see save as well. ## Prerequisites There is one step you need to complete previous to working through this guide. 1. If you do not already have a GitHub account, visit [GitHub signup](https://github.com/signup) to create a new account. That's it! ## Acknowledgements Thank you to GitHub user [rzashakeri](https://github.com/rzashakeri) for putting together a massive list of tools to help [Beautify your GitHub Profile](https://github.com/rzashakeri/beautify-github-profile). The tools demonstrated in this guide are all pulled from this list. # Create an Excellent GitHub Profile with Markdown ## Create Your Repository The first step towards putting up your GitHub profile is to create the special repository designed to contain it. The images show the author's GitHub account, however, yours should look similar enough to follow along. ## Creating a New Repository Visit the main page of your GitHub account at the URL, **https://github.com/YOUR\_GITHUB\_USERNAME/** , e.g. [https://github.com/kattni/](https://github.com/kattni/). You should see something similar to the image below. If your account is brand new, you won't see popular repositories and so on. The important part is the set of tabs towards the top. Click on the **Repositories** tab. (The number next to it will differ based on your account and potential previous contributions.) ![](https://cdn-learn.adafruit.com/assets/assets/000/112/312/medium800/programming_GFP_main_GItHub_account_page.png?1654805383) Inside the Repositories tab, you'll find a green button titled "New". Click the **New** button. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/313/medium800/programming_GFP_in_Repos_tab_click_New.png?1654805495) This button takes you to the repository creation page, which begins with two prompts and a new repository name suggestion, in this case, "effective-chainsaw". (Suggestions are randomised.) ![](https://cdn-learn.adafruit.com/assets/assets/000/112/314/medium800/programming_GFP_initial_new_repo_page.png?1654805599) Now, you'll want to fill in the **Repository name** dialogue box with the same name as your account, using the same spelling, formatting, etc. as you do for your account name. The name listed as **Owner** to the left of the **Repository name** dialogue box is your account name, so you can refer to that if you're unsure. Once you fill in the **Repository name** with your account name, you'll see a box pop up below it explaining that this repository is special, why it's special, and how to fill in the rest of the page to use it as intended. You can optionally fill in the **Description** as well, but it is not necessary. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/315/medium800/programming_GFP_Fill_in_repo_name_and_desc.png?1654806113) The next section of the new repository page determines whether the repo is public, where everyone can see it, or private, where only you can see it. It defaults to **Public** and you should leave it as such. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/316/medium800/programming_GFP_leave_repo_as_public.png?1654806277) The following section asks whether you want to include a few things in your brand new repository. You definitely do! Check the box to **A**** dd a README file**. You can leave the rest as is. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/317/medium800/programming_GFP_check_Add_a_README_file.png?1654808365) You're now ready to create your new repository. Click the **Create repository** button. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/318/medium800/programming_GFP_click_Create_repository.png?1654808473) After a moment, you'll be taken to your new repository, which should look something like the following. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/319/medium800/programming_GFP_view_of_new_repository_after_creation.png?1654808661) That's the process for creating a new personal profile repository on your GitHub account! # Create an Excellent GitHub Profile with Markdown ## Markdown Basics **Markdown** is a lightweight markup language with simple syntax for creating formatted text. Put more simply, Markdown makes it easy to create formatted text for a variety of uses not including GitHub, such as blogging. certain messaging platforms, documentation, and specific to what you're interested in today, README files. GitHub uses its own version of Markdown, referred to as **GitHub Flavored Markdown**. It also supports rendering Markdown (.md) files, which is to say, if you add a Markdown file to a GitHub repository, it will show up formatted when you click on it on GitHub. Adding a **README.md** file to a _normal_ GitHub repository will render it below the list of files contained within the repo. Adding a README to your special new repository will render it on your main account page on GitHub! However, before you can get started with making your new profile, you're going to need to have a basic understanding of Markdown. This page will cover some basics, and include a link to a separate guide that goes into more detail. # Markdown Syntax Creating headings, and **bold** , _italic_, and strikethrough formatted text (as well as various combinations thereof) are simple to do with Markdown. ## Markdown Headings Headings are formatted using various numbers of **#** in front of the heading text. One **#** indicates the largest heading, two **#** indicate the second largest heading, and six **#** indicate the smallest possible heading. The following is an example of Markdown headings. ```html # Sample Heading Text ## Sample Heading Text ###### Sample Heading Text ``` The above Markdown renders as shown below. # Sample Heading Text ## Sample Heading Text ###### Sample Heading Text ## Markdown Text Formatting Text formatting with Markdown is relatively simple, once you get the hang of it. A few basic formatting options are included below. - The first column is the specific formatting style. - The second column is the Markdown formatting. **The formatting options shown once are expected to be on both sides of the text you wish to format. See third column for examples.** - The third column is an example using the Markdown. - The fourth column is the Markdown example rendered. | Style | Markdown | Example | Rendered | | ------- | --------------- | ------------ | -------------- | | Bold | `**` or `__` | `**Bold text**` or `__Bold Text__` | **Bold text** or __Bold text__ | | Italics | `*` or `_` | `*Italics text*` or `_Italics text_` | *Italics text* or _Italics text_. | | Strikethrough | `~~` | `~~Strikethrough text~~` | ~~Strikethrough text~~ | | Bold and nested italics | `**` and `_` | `**Bold and nested _italics_ text**` | **Bold and nested _italics_ text** | | Entirely bold and italics | `***` | `***Entirely bold and italics text***` | ***Entirely bold and italics text*** | ## Markdown Image Embedding Markdown allows you to easily embed images that you have uploaded to GitHub. Add an exclamation point, `!`, to the start of the line,  immediately followed by the alt text wrapped in brackets, `[]`, immediately followed by the image link wrapped in parentheses, `()`. Here is an example image embed line. `![The Adafruit Discord Badge](https://raw.githubusercontent.com/adafruit/Adafruit_CircuitPython_Bundle/main/badges/adafruit_discord.svg)` This line would render the following image: ![The Adafruit Discord Badge](https://raw.githubusercontent.com/adafruit/Adafruit_CircuitPython_Bundle/main/badges/adafruit_discord.svg) Check out the [Add an Image page](https://learn.adafruit.com/excellent-github-profile/add-an-image) in this guide for details on how to upload an image to GitHub. ## Markdown Code Formatting Markdown makes it simple to include formatted code snippets. To format code inline or line-by-line, include **`** (a single backtick) on either side of the code to render it as code. For example, `Hello, World!` would render as `Hello, World!`. To format a codeblock, include **```** (three backticks) on either end of the codeblock. For example: ```python ``` print("Hello, World!") while True: print("This is a loop!") ``` ``` Would render as: ``` print("Hello, World!") while True: print("This is a loop!") ``` ## Markdown List Formatting Making lists with Markdown is pretty intuitive. For a bullet list, use either **\*** or **-** at the beginning of each line in the list. For example, the following: ```auto * Bullet line one * Bullet line two or - Bullet line one - Bullet line two ``` Would render as: * Bullet line one * Bullet line two or - Bullet line one - Bullet line two For numbered lists, you would use a number followed by a period, such as **1.** , at the beginning of each line. For example: ```auto 1. Numbered line one 2. Numbered line two ``` Would render as: 1. Numbered line one 2. Numbered line two ## A Nifty Collapsing Trick You may find that your Markdown file is getting a bit long. Perhaps some of the information is important to you to include, but might be secondary to other more crucial information. Wouldn't it be convenient to display a by-default collapsed section that folks can click on if they are interested in more information? Here's a nifty trick to do exactly that. To create a collapsed section your Markdown file, include the following code. ```auto ### A collapsible section with Markdown <details> <summary>Click here for more information!</summary> More information here. </details> ``` Two important notes: 1. You must leave an empty line below the closing `</summary>` tag, otherwise the Markdown will not render properly. 2. Leave an empty line below the closing `</details>` tag if you have multiple collapsing blocks. # GitHub Flavored Markdown Resources For a more in-depth look at GitHub Flavored Markdown basics, check out this excellent [Basic writing and formatting syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) guide. It covers everything covered here including more detail, and a number of formatting options not covered here. If you're interested in some more advanced formatting, check out the next section in the same guide, [Working with advanced formatting](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting). # Create an Excellent GitHub Profile with Markdown ## Edit Your README Now that you have the Markdown basics figured out, it's time to learn how to edit your README. Following repository creation, GitHub took you to the README. If you left the browser window alone, you should be looking at something similar to the following. Click the green **Edit README** button to continue. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/346/medium800/programming_GFP_view_of_new_repository_after_creation.png?1655153215) If you clicked away from it or refreshed, the green button may not be present, in which case, you're looking at something similar to the following. Click the "pencil" shaped **Edit** button to continue. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/348/medium800/programming_GFP_click_edit_readme.png?1655154205) Either way, you'll open the GitHub file editor, which includes two major sections: the file content editor, and the Commit changes section. First up: the editor. ## GitHub File Editor The top section is the file editor. This section is where you'll spend most of your time when editing your README file. The green alert won't show up on any other file you edit on GitHub, as it is related specifically to this file. At the top of this section you can edit the filename (indicated by the magenta arrow). Don't do that! It must be named **README.md** to work for this purpose. Below the alert is the actual content editor (indicated by the orange arrow). ![](https://cdn-learn.adafruit.com/assets/assets/000/112/349/medium800/programming_GFP_readme_editor_file_and_content.png?1655155825) There are two key features to the file content editor. There are two tabs at the top, titled **Edit file** and **Preview**. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/351/medium800/programming_GFP_file_editor_tabs.png?1655156608) The file editor begins in the **Edit file** tab. Below it, is the content editor itself. As you can see, this README was generated with preexisting content. Any README you generate using the checkbox at repository creation will have some content, but this README is special, and therefore, so is its content. When it comes down to it, though, one of the greatest things about the GitHub file editor is the **Preview** tab. The Preview tab is magical. It allows you to view your content the way GitHub will render it once you "save" the file. So, you can make incremental changes, and view how they will appear every step of the way. That way, you know for certain the content you added looks exactly like you want it to. And, if it doesn't? You can continue to update it and verify it until it does. Here is what the content looks like in the editor (on top), and how it is rendered by GitHub in the preview (on the bottom). ![](https://cdn-learn.adafruit.com/assets/assets/000/112/352/medium800/programming_GFP_editor_preview_together.png?1655159651) You may have noticed that the file preview doesn't quite match the file content. The only thing rendered was the first line and the third line added by you. That is because the rest of the Markdown is what is referred to in programming as "commented out". Commenting something out means you can include something in your file, such as a note or comment, and have it be ignored when the file is rendered. When you generate your personal repo and include a README, it comes populated with a short list of prompts to get you started. GitHub provides a starting point for profile content commented out to allow you to choose to add it to your profile or not. ## Editing Content Now that you've explored the editor, it's time to dig into editing the content. "Hi there" is pretty generic. How about adding an intro to yourself by name? Click the **Edit file** tab if you're not already in the editor. Click to line 2 in the code and hit enter once to put a line between the header and where you're about to type. You should now be on line 3. Add the text, "I'm \!" The top of your file should look something like the following. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/421/medium800/programming_GFP_first_edit_intro.png?1655236082) Click the **Preview** tab. You've now introduced yourself! ![](https://cdn-learn.adafruit.com/assets/assets/000/112/422/medium800/programming_GFP_intro_preview.png?1655236119) You now know how to do basic content editing on your README. You'll get into more detail later in this guide. ## Committing Content As with any file on your computer, once you edit it, you need to save your changes. On GitHub, "saving" your changes is called **committing** , and the point at which you save your file is called **a commit**. Creating commits regularly ensures you never lose much work. This is where the second section on this page comes in - the **Committing changes** section. Scroll down to the bottom of the page, and you'll find the **Committing changes** section. Yours should look something like this. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/424/medium800/programming_GFP_readme_editor_commit_changes.png?1655236485) The first box is where you can add your commit title. It currently says in grey "Create README.md", and if left as-is, the commit title will be "Create README.md". This is the only box for which this is the case. Commit titles are typically less than 50 characters, so you want to be brief and concise. This is what will be associated with your save on GitHub. While you can leave it as the default, it can also be really helpful to update it to something more specific to your change so you know at a glance what your last update was. The second, larger box is for your commit message. This is optional. Though it also has grey text, it will be left empty if you do not add your own text. You're welcome to add more details in the commit message box regarding your changes, but it is not necessary to do. If you have more than one email address associated with GitHub, you'll see the drop-down under the commit message box allowing you to choose which email address you want associated with this commit. Finally, there are two radio dials. The first says "Commit directly to the `main` branch." The second says "Create a **new branch** for this commit and start a pull request." Since this is your personal repository, and you are the only one working on this file, you'll leave this section in the default state with the first dial selected. Since you added an intro,  you can update the commit title to "Added basic intro." As there's not much else to it, it's fine to leave the commit message blank. So your **Commit changes** section should now look like this. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/425/medium800/programming_GFP_adding_intro_commit_changes.png?1655237349) The final step is to click the green **Commit changes** button. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/426/medium800/programming_GFP_Click_commit_changes.png?1655237527) This will commit your changes and return you to the README file as it shows up on GitHub. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/427/medium800/programming_GFP_README_following_commit.png?1655237603) That's what goes into editing your README and committing your changes to save them to GitHub! Obviously, you'll want to add more content than that. What else can you add? For those who aren't sure where to begin, the next section discusses ideas for profile content. # Create an Excellent GitHub Profile with Markdown ## Profile Content You've learned how to create and edit the README file that contains your profile content. Now, you have to figure out what to include. This can be intimidating. For some, it can be a struggle to get past questioning whether there is anything other folks might be interested in knowing about them in the first place. For others, it's simply a matter of drawing a blank when asked to introduce themselves. Well, guess what? Whether you realise it or not, you have interesting things about yourself to share, and your GitHub profile is a great place to do so. ## Considerations The first step is to consider your goal for your profile. There are a wide variety of options. Here are a few concepts to start with. - Do you want to introduce yourself personally? - Do you want to introduce yourself professionally? - Do you want to showcase projects you're working on? - Do you want to feature your community involvement? - Do you want to highlight your GitHub usage stats? - Do you want to give readers options to contact you? You don't have to choose only one concept. Your profile an be any combination of them, up to and including all of them! There are many more options available, so don't let this list limit you. ## Personal Content You are a vibrant person with many important things to share! It's impossible to cover all of them here. However, you need to start somewhere, and this section will help you do that. Think about introducing yourself in person. What do you say? The first thing is probably your name and pronouns. The specific situation likely determines what you say next. Among friends? Presumably you include a couple of interesting personal bits about yourself. Exactly like introducing yourself in person, you can begin your profile with similar information. Here is some other personal information you can consider adding to your profile. Examples are in _italics_. - General personal info: _   _ e.g. _"I have two cats."    _ e.g. _"I have a three foot long beard."_ - Personal interests or hobbies:     e.g. _"I am interested in astrophysics."_     e.g. _"My hobbies include programming and photography."_ - Skills you've gained in your personal time.     e.g. _"I am proficient at woodworking and jewelry making."_ - Personal projects you're working on:     e.g. _"I'm currently working on building a dining room table."_     e.g. _"I'm currently designing a program to sense temperature and humidity in my house."_ - Places your personal work has been featured:     e.g. _"My first open source contribution was writing the CircuitPlayground library."_     e.g. _"One of my paintings was on exhibition in a NYC art collection."_ - Personal goals:     e.g. _"I want to learn programming."_     e.g. _"I want to foster kittens."_ - Things about yourself that you value:     e.g. _"I strive to pass the things I learn onto others."_ - Places you've lived or travelled to:     e.g. _"I've lived in the US and Canada."_     e.g. _"I've travelled to Ireland and Italy."_ - Languages you speak and fluency:     e.g. _"I speak Spanish fluently, and French conversationally."_ - Things you wish to complete in your lifetime:     e.g. _"I want to touch a blue whale."_     e.g. _"I want to travel to every continent."_ - Arbitrary fun fact about you: 
    e.g. _"I'm related to an Olympic gold medalist."_ 
    e.g. _"I have one and a half lungs."
_     [Doesn't need to be serious! Be cheeky if you'd like!]
     e.g. _"Not famous enough for a Wikipedia page."_ This is not an exhaustive list (obviously), but it should serve as a starting point for you. ## Professional Content Whether you work with code on GitHub professionally, or you simply want to highlight your professional life, your GitHub profile is an excellent venue. Again, think about your in-person introduction, but this time, in a professional setting. How would you want to introduce yourself professionally? Here are some ideas. - Current employment info & responsibilities:     e.g. _"I work with Adafruit."_     e.g. _"I work at a Fortune 500 company designing children's toys."_ - Past employment info & responsibilities:      e.g. _"I previously worked in health care."_     e.g. _"I managed an IT solution that optimized three global ERP instances."_ - Professional projects you're involved with:     e.g. _"I work on the CircuitPython project."_     e.g. _"I write automation using Python for IoT-enabled devices."_ - Skills & relevant topics you've cultivated through work:     e.g. _"I am a successful community leader."_     e.g. _"I have experience with microcontrollers."_     e.g. _"I am an experienced developer advocate."_ - Where your professional work has been featured - showcase your skills and projects together:     e.g. _"You can find my documentation in the Adafruit Learn System and on GitHub."_     e.g. _"I am a CircuitPython developer, and you can find my contributions in the Adafruit CircuitPython libraries."_ - Professional goals:     e.g. _"I want to be a senior software architect."_     e.g. _"My goal is to create software & hardware solutions that are accessible world-wide and can help many people."_ There are definitely ways to expand upon what's laid out here. This should get you going. ## Community Content Community content isn't limited to you specifically being involved with a particular community. It also applies to you expressing a desire to work with others on projects, or to share your knowledge with others. Here are a few suggestions. - Personal & professional communities you're involved with [Open Source, non-profit, commercial, or otherwise]:     e.g. _"I am a community leader for the Adafruit and CircuitPython communities."_     e.g. _"I served on an advisory board for IEEE."_ - Projects & opportunities that you would like to collaborate on:     e.g. _"I am looking to build long-distance LoRa agricultural monitoring."_     e.g. _"I measure the vitals of rescue animals, and I'd like to automate the process."_ - Skills or projects you'd like to get help with:     e.g. _"I am looking for help learning Python."_     e.g. _"I'm interested in applying educational & game theory so beginner projects are more approachable."_ - Knowledge or concepts you'd be interested in sharing with others:     e.g. _"I am happy to discuss my skills in technical writing and community leadership."_     e.g. _"I'm a digital artist who enjoys making animation techniques & synthesizers accessible for beginners, and would love to share."_ - Volunteering efforts:     e.g. _"I volunteer my time at the local pet shelter."_     e.g. _"I've volunteered at my local Maker Faires."_ These are only a few ideas for community content. Include any type of involvement with others, past, current and future. ## GitHub Statistics This section is specific to those who use GitHub regularly and are interested in showcasing their usage statistics. Here are a few types of statistics you might want to include. - Stars - Commits - Pull requests - Issues - Repositories you've contributed to - Your most used languages There are plenty more to include as well. The easiest way is to use the available tools discussed later in this guide. They allow you to include dynamically updated stats in customisable ways. ## Contact Info An important part of a profile, for many, is providing readers a way to find you. Here are a few suggestions. - Email address(es) - Signal or WhatsApp number - Twitter, Mastodon or other social media platforms - Personal website, blog, or other web presence - Facebook, Instagram, etc. Whether you frequent Twitter, your personal blog, or other various places on the internet, your profile is a great place to help folks to be able to find you beyond GitHub.  ## Existing GitHub Profiles [Awesome GitHub Profile READMEs](https://zzetao.github.io/awesome-github-profile/) is an aggregated list of various folks' GitHub profiles. If you're interested to see what others are including in theirs, this list is an excellent resource to check out. # Create an Excellent GitHub Profile with Markdown ## Create Your Profile ![](https://cdn-learn.adafruit.com/assets/assets/000/112/632/medium800/programming_GFP_README_general_for_overview.png?1656286417) The next step is to create your profile. There are a wide variety of options to do this. This section starts simple and moves into more involved tools. It will discuss various ways to create content, from a simple profile using the initial GitHub-generated content, to profile Markdown generators, to tools designed to help you add features to your profile. Whatever "excellent" means to you, this section will help you create an excellent GitHub profile! # Create an Excellent GitHub Profile with Markdown ## GitHub Provided Content As you may recall, when you created your README, it came with some extra content that didn't show up in the preview or when you committed your changes. Why is that? The rest of the Markdown in the GitHub-generated README is what is referred to in programming as "commented out". Commenting something out means you can include content in your file, such as a note or comment, and have it be ignored when the file is rendered. When you generate your personal repo and include a README, it comes populated with a short list of prompts to get you started. GitHub provides a starting point for profile content commented out to allow you to choose to add it to your profile or not. The simplest of profiles can be created with very little effort on your part. Simply fill in the prompts provided in the README, and you'll have a basic introduction of yourself ready to go. ## Using the Provided Content To utilise the GitHub-provided prompts, you're going to "uncomment" the rest of the content in the file. To do this, you will delete the content on two lines. The line numbers are assuming you added your brief intro in the previous section of this guide. Remove the `<!--` on line 4, and the `-->` on line 17. Your file content should now look like the following. Info: ![](https://cdn-learn.adafruit.com/assets/assets/000/112/560/medium800/programming_GFP_uncomment_existing_content.png?1655928844) Now click the Preview tab to see what your changes look like. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/561/medium800/programming_GFP_initial_existing_content_preview.png?1655928871) Excellent! The extra Markdown in the file is no longer commented out, so it shows up in the preview. Click back over to the editor. The text on lines 5 and 7 are clearly meant to be info for you, and not meant to be included in the profile. Go ahead and delete those lines. Your file should look like the following. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/562/medium800/programming_GFP_prompts_minus_repo_info.png?1655929066) Now, simply fill in the prompts you would like to include in your profile. If there are any you'd rather not include, simply delete them. Once completed, your file should look something like the following. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/564/medium800/programming_GFP_prompts_filled_in.png?1655936819) Click Preview to see what it will look like. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/565/medium800/programming_GFP_prompts_filled_in_preview.png?1655936923) Finally, [commit your changes](https://learn.adafruit.com/excellent-github-profile/edit-your-readme#committing-content-3119912-17). Your new profile is now ready to go! You're always welcome to add more, but this is a great start. # Create an Excellent GitHub Profile with Markdown ## Create a Header Image ![](https://cdn-learn.adafruit.com/assets/assets/000/112/602/medium800/programming_GFP_GitHub_Profile_Header_Generator.png?1656017288) GitHub user [leviarista](https://github.com/leviarista) created the really nice and easy-to-use [GitHub Profile Header Generator](https://leviarista.github.io/github-profile-header-generator/). This tool is designed to help you quickly create a unique header image to include in your profile. The GitHub Profile Header Generator provides you with a series of settings you can tweak to create a header image that works for you. # Using the GitHub Profile Header Generator On the right side, you'll find three sections, the preview, the buttons, and the customisations, the last of which has three tabs. ## Preview The preview is what your header image will look like. As you customise it, the preview will update dynamically to show your changes. Here is the default image preview. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/603/medium800/programming_GFP_GPHG_preview.png?1656018137) ## Buttons Below the preview are three buttons: **dark mode** , **randomize** and **download**. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/604/medium800/programming_GFP_GPHG_dark_mode_randomize_download.png?1656018240) The **dark mode** button swaps the Header Generator between light and dark mode. It defaults to dark mode. Swapping modes only seems to affect the black background behind the preview and the buttons. The **randomize** button creates a randomised header for you. As you click the button, the preview will change. Note that you will still need to add your info below. The **download** button downloads the image to your computer. ## Customisations Below the buttons is the customisations section, which is made up of three tabs containing all of the customisation options available to you for your header image. The three tabs are **Main** , **Background** , and **Decorations**. ### Main Tab The **Main** tab allows you to update the text shown on the header image, including content, color, alignment, style, and size, as well as the overall size and padding of the image. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/605/medium800/programming_GFP_GPHG_main_tab.png?1656018707) The first and most important thing to change is the first two boxes in the main tab. The first box is the **Title** content and the second box is the **Subtitle** content. They default to "Hey! I am ..." and "Fullstack developer", respectively. Delete the current content and add your own. The idea is to introduce yourself by name, and then include a few important things about you. Info: ### Background Tab The **Background** tab lets you customise the background including the background color, whether there is a border, and if so, the border color. It also allows you to add a pattern to the background, choose a color for the pattern, and decide on a size and opacity for the pattern. There are various patterns available at the bottom of the tab. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/606/medium800/programming_GFP_GPHG_background_tab.png?1656019065) ### Decorations Tab The **Decorations** tab enables you to add small decorative images to your header image. You have the option to change the size of the decoration. There are a few decorations provided. One of the best things about this tool is that it allows you to upload your own decoration image. It is confirmed to support PNG and SVG formats, but it may support many more as well. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/607/medium800/programming_GFP_GPHG_decorations_tab.png?1656019276) ## Example Header Image Here is an example header image, generated using this tool. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/608/medium800/programming_kattni-github-profile-header-image.png?1656019335) Now you have a lovely, informative header image to add to your profile! # Create an Excellent GitHub Profile with Markdown ## Add an Image Markdown makes it simple to embed images in your GitHub profile. First, however, you will need to upload the image to your GitHub profile repository so you can link to it from there. This page will walk through the steps to create a new directory in your repo, and upload your image to the new directory. Pick an image you'd like to include in your profile. If you simply wish to follow along, any image will do! ## Create a New Directory with a README It's simple to create a new directory in a repository on GitHub. However, to do so, you must add a file to it. This is not an issue as it is always a good idea to put a simple README in a GitHub directory to explain what the directory is for. It can obviously be more detailed than that, but for our purposes, simple is perfect. On GitHub, go to the main page for your special repository. You'll see an **Add file** dropdown. Click Add File, and then click **Create new file**. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/582/medium800/programming_GFP_click_Add_File_then_Create_new_file.png?1656012429) In the empty box at the top, preceded by your repo name followed by /, you'll want to type the following: **assets/** As soon as you type **/** , it will turn it into a directory under the repo name, leaving you with a newly empty box to enter a file name. Enter the following: **README.md** Now, click in the file editor, and add a Markdown level two heading with a quick description of what will be in this directory. The edited sections should now look something like this: ![](https://cdn-learn.adafruit.com/assets/assets/000/112/583/medium800/programming_GFP_type_assets_README_dot_md_add_text.png?1656012618) Now, [commit your changes](https://learn.adafruit.com/excellent-github-profile/edit-your-readme#committing-content-3119912-17). Once committed, you should see something similar to the following. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/584/medium800/programming_GFP_assets_README.png?1656012910) You'll find an **Add file** dropdown towards the top-right. Click Add file, and then click **Upload files**. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/585/medium800/programming_GFP_click_Add_file_then_Upload_files.png?1656012974) Once in the file upload dialogue, you'll see clear instructions as to what to do next. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/586/medium800/programming_GFP_GitHub_upload_files_instructions.png?1656013091) You have two choices: you can drag a file to that section of the window, or you can click **choose your files** and upload through a file explorer dialogue. Choose your method, and upload your image file. You'll see the following while it uploads. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/587/medium800/programming_GFP_file_uploading.png?1656013365) Once uploaded, it will show up below the instruction box, appearing something like the following. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/588/medium800/programming_GFP_uploaded_file.png?1656013382) [Commit](https://learn.adafruit.com/excellent-github-profile/edit-your-readme#committing-content-3119912-17) the uploaded image exactly as you would changes to your README files. Once committed, it should return you to the main page of your repository. Here you'll find your new **assets** directory. Click it. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/589/medium800/programming_GFP_new_assets_directory.png?1656013479) Within it, you'll find the image you uploaded. You can click it to view it, if you like. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/590/medium800/programming_GFP_uploaded_image_in_assets_directory.png?1656013501) Now you have an image you can link to. This means you're ready to include an image in your GitHub profile using Markdown! # Create an Excellent GitHub Profile with Markdown ## Markdown Generators You've created your repository, and learned a bit about Markdown and editing the README. How are you feeling? Ready to dig into writing your profile from scratch using Markdown? Or, possibly feeling like you're in a bit over your head? You are here because you're interested in creating your GitHub profile, but perhaps you weren't prepared for what goes into it. That's okay! There are multiple tools available that make it simple to generate the necessary Markdown so you can simply copy and paste it into your README file. This page will discuss the [GitHub Profile Readme Generator by Arturs Smirnovs](https://arturssmirnovs.github.io/github-profile-readme-generator/). When you generate the README for your special personal repo, GitHub provides a set of prompts at the bottom of the file. Most of the various GitHub profile generators are, at least initially, based on those prompts. # GitHub Profile Readme Generator ![](https://cdn-learn.adafruit.com/assets/assets/000/112/468/medium800/programming_GFP_GitHub_Profile_Readme_Generator_overview.png?1655332892) The [GitHub Profile Readme Generator](https://arturssmirnovs.github.io/github-profile-readme-generator/) is contained within one page, with the different profile info sections being editable in four tabs. Here are some positive things about this README generator: - It is available in English and Spanish. - It shows a dynamic preview of what your README will look like as you enter information. The top of the page allows you to choose which language you would like to use. After that, there are three sections of the page that you'll want to focus on to generate your README content. ## Preview Section This section previews your changes dynamically as you enter information. (Remember, it's initially prefilled with information from the creator.) As you update the information in the next section, your info will show up in the preview section, as it will in your GitHub profile. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/477/medium800/programming_GFP_GPRG_preview_section.png?1655334105) ## Information Input Section The first section to focus on is the four tabs and everything below them in the bottom left of the page. ### Header Section The **Header** section, as titled, contains the various parts of your profile header. It allows you to specify a heading, a subtitle, a short bit about you, a list of skills, and a banner URL (such as the URL to the image you may have added [earlier in this guide](https://learn.adafruit.com/excellent-github-profile/add-an-image)!). ![programming_GFP_GPRG_input_Header_section.png](https://cdn-learn.adafruit.com/assets/assets/000/112/473/medium640/programming_GFP_GPRG_input_Header_section.png?1655333667) This section is prefilled with example content. You will replace this content with your own information, or delete it and leave the box blank if you do not want to add a particular item to your header. Info: ### Additional Information The **Additional** section provides a series of prompts that you can fill in if you wish. (Look familiar? This section is based on the prompts provided by GitHub when you initially generated your README!) There is no default info filled in here, so simply fill in the ones you want to include, and leave blank those you do not. ![programming_GFP_GPRG_input_Additional_section.png](https://cdn-learn.adafruit.com/assets/assets/000/112/474/medium640/programming_GFP_GPRG_input_Additional_section.png?1655333710) ### Social Information The **Social** section contains a default list of social media accounts, with space to include your username for that platform. There is also a spot to include your website. When filled in, they will show up as the icon (shown next to the platform in the list) in your profile which folks can click on. ![programming_GFP_GPRG_input_Social_section.png](https://cdn-learn.adafruit.com/assets/assets/000/112/475/medium640/programming_GFP_GPRG_input_Social_section.png?1655333812) Don't see your favorite social media platform on the list? Under Others, towards the bottom of the section, you'll find an _extensive_ list of further options. ### Other Information The **Others** section requires your GitHub username at the top. Once entered, under the headings within the section, the checkboxes will become available for clicking. You can click on each one to see the widget rendered in the profile preview. Add as many or as few widgets, etc, from this section as you like. ![programming_GFP_GPRG_input_Others_section.png](https://cdn-learn.adafruit.com/assets/assets/000/112/476/medium640/programming_GFP_GPRG_input_Others_section.png?1655333845) ### Updated Preview Here is what the top of the preview looks like after custom information has been filled in. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/553/medium800/programming_GFP_GPRG_preview_with_info.png?1655923448) ## Code Section This section shows you the Markdown code to produce the preview. It is updated dynamically as you enter information. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/478/medium800/programming_GFP_GPRG_code_section.png?1655334227) ### Updated Code Here is what the top of the code looks like for the previously filled custom information. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/554/medium800/programming_GFP_GPRG_code_with_info.png?1655923546) ## Updating Your README Now that you've entered all of your desired information into the Generator, it's time to transfer the provided code to your GitHub README file. Above the Code section, in the upper right corner of the section, you'll see a blue **Copy** button. Click it to copy the contents of the code section. Once you click, you'll see all of the code in the content box highlighted. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/556/medium800/programming_GFP_GPRG_copy_code_button.png?1655925015) Now, head back over to GitHub and your README file. If you are not already in the file editor, click the **Edit README** button, or the **pencil icon** to enter the file editor. This code is intended to replace all the current content in your README. If you have anything in there you'd like to keep, make sure you copy it out of the file editor before continuing. Click into the file editor. Select all the text. Then paste the contents of the clipboard (which should be the Markdown code you copied from the Generator). This is what the top of the file editor looks like with the generated content. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/557/medium800/programming_GFP_GPRG_GitHub_file_editor_content.png?1655925537) Now click the Preview tab to see what it will look like on GitHub. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/558/medium800/programming_GFP_GPRG_GitHub_content_preview.png?1655925621) As explained in the [Edit Your README](https://learn.adafruit.com/excellent-github-profile/edit-your-readme#committing-content-3119912-17) section, save the new content by committing your code to GitHub. # Other Options If you're looking for a less involved but sleek looking profile, check out the [GitHub Profile Readme Maker by Vishwa Gaurav](https://gprm.itsvg.in/). The [GitHub repository by rzashakeri](https://github.com/rzashakeri/beautify-github-profile#7--github-profile-readme-generator) contains a number of other options as well, beginning with number 7 in the list (the link takes you directly there). You'll likely want to search in page for "generator" to find all the possibilities, as they are spread throughout the list. # Create an Excellent GitHub Profile with Markdown ## Markdown Content This guide explained some basic Markdown, and linked to an [excellent guide from GitHub](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) with more details. Whether you've picked up enough Markdown from these resources, or you were already familiar with Markdown, you may want to simply generate your own content. This does not limit you to adding further features to your profile. You can always begin with your own Markdown content and include some of the enhancements discussed later in this guide. If you found this page first, and you're not sure where to begin technically speaking, you're best off starting at [the beginning of the guide](https://learn.adafruit.com/excellent-github-profile/overview). If you're not sure where to start content-wise, check out the [Profile Content page](https://learn.adafruit.com/excellent-github-profile/profile-content) in this guide. Now... Start. Your. Profile! ## Composing Your Own Profile Content The first step is [editing your README](https://learn.adafruit.com/excellent-github-profile/edit-your-readme), entering the file editor, and deleting the existing content. Many profiles begin with a name and a brief introduction. This can include either a personal or a professional introduction (or both!). This doesn't mean you have to follow along with the crowd. You can make it wacky and fun! The important part is that the final product represents you in a way with which you're satisfied. The following shows the beginning of example profile content including a header image, a number of links, and divided into multiple sections. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/610/medium800/programming_GFP_DIY_Markdown_profile_example.png?1656096399) Once you get some idea what you want to include, and how you want to format it, you can add to your README file. Throughout the process, remember to [commit your changes](https://learn.adafruit.com/excellent-github-profile/edit-your-readme#committing-content-3119912-17). It's best to save your changes regularly, so there's no chance of you losing your work! The example shown above looks pretty lengthy; there's more content beyond the screenshot. However, remember that all of the links will render as hyperlinked inline text. Below is the preview of the content in the screenshot above. (Font size is directly related to the zoom level you have on GitHub, and cannot be otherwise specified. Basically, if you want smaller font, zoom out on GitHub in your browser.) ![](https://cdn-learn.adafruit.com/assets/assets/000/112/611/medium800/programming_GFP_DIY_Markdown_profile_preview.png?1656096689) Once you're happy with your text content, you can choose to stop there, or to continue on to adding a few enhancements to your profile. It's completely up to you! # Create an Excellent GitHub Profile with Markdown ## Skill Icons and Badges Your GitHub profile is a great place to highlight your skills. You could create a bullet list of your skills in your profile, but why do that when you can easily include skill icons and badges instead! ## Skill Icons User [tandpfun](https://github.com/tandpfun) on GitHub created a fine set of [skill icons](https://github.com/tandpfun/skill-icons), including information on how to apply them to your GitHub profile. They provide a lovely list of icons, and make it simple to display in your profile! Info: ![](https://cdn-learn.adafruit.com/assets/assets/000/112/615/medium800/programming_GFP_skill_icons_repo.png?1656107900) The [documentation README](https://github.com/tandpfun/skill-icons#docs) is thorough and explains exactly how to use the tool, configure the format, and what icons are available. Definitely check that out for more detail. It begins with a [screenshot of the author's profile](https://github.com/tandpfun/skill-icons#example), including a number of the skill icons available for use. The next few sections explain how to [specify which icons](https://github.com/tandpfun/skill-icons#specifying-icons) you want to display, alter the [icon theme](https://github.com/tandpfun/skill-icons#themed-icons), specify the [number of icons per line](https://github.com/tandpfun/skill-icons#icons-per-line), and [center the icons](https://github.com/tandpfun/skill-icons#centering-icons). Finally, there is a [list of all the available icons](https://github.com/tandpfun/skill-icons#icons-list) including the name you would use when you choose to display a specific icon. For example, to add a short list of skills to a GitHub profile, you would include the following line of Markdown in your README. ```auto ![My Skills](https://skillicons.dev/icons?i=py,git,github,discord,bootstrap,arduino) ``` The above Markdown will render as follows in your profile: ![My Skills](https://skillicons.dev/icons?i=py,git,github,discord,bootstrap,arduino) You can follow the documentation to configure the available settings, if you wish. There are other options for skill icons available on the [Beautify GitHub Profile repo](https://github.com/rzashakeri/beautify-github-profile) as well, if you don't find everything you want to highlight in this list. ## Skill and Various Badges There are many options for badge creation. The [Beautify GitHub Profile](https://github.com/rzashakeri/beautify-github-profile) list contains a [Badges](https://github.com/rzashakeri/beautify-github-profile#-badges-) section with 26 options. Users [Naereen](https://github.com/Naereen) and [Ileriayo](https://github.com/Ileriayo) on GitHub put together a [badges repo](https://github.com/Naereen/badges) and a [markdown-badges repo](https://github.com/Ileriayo/markdown-badges), respectively, each divided up into categories, and including the Markdown code necessary to add them to your GitHub profile README. Check out the READMEs in each repo for more details on usage and for the Markdown necessary to render the available badges. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/617/medium800/programming_GFP_markdown-badges_repo_header.png?1656111214 The header on Ileriayo's Markdown Badges list.) All of the badges available on Ileriayo's list are generated on [Shields.io](https://shields.io/). Shields.io is a site for generating static and dynamic badges for a wide variety of skills and topics. The badges on Naereen's list are pulled from various sites. You can sort out where they were generated by looking at the URL in the suggested Markdown code. For example, this Generic badge on Naereen's list was generated on Shields.io. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/618/medium800/programming_GFP_Naereen_badge_list_Generic_badge.png?1656120414) The nice thing about Naereen and Ileriayo's lists are that they provides a lengthy list of example badges to get you started. If you're more interested in generating your own, there are a number of options. A very popular option for generating your own badges is [Shields.io](https://shields.io/). ![](https://cdn-learn.adafruit.com/assets/assets/000/112/619/medium800/programming_GFP_shields_io_header.png?1656182178) The main page is made up of two major sections, the latter of which has a number of subsections. The first section is a list of categories that contain existing badges, which you can search using the **search / project URL** dialogue at the top of the page. The second section provides the option to create your own badge, either static or dynamic, and provides the URL query strings necessary to configure your badge style. There are details on each of the style options in the Styles section. When you generate a badge, it will switch to the relevant URL and page containing your badge. This is the URL to a simple static badge. To use, you would add the following line of Markdown to your profile. ```auto ![Theoretically Productive](https://img.shields.io/badge/THEORETICALLY-PRODUCTIVE-blueviolet) ``` Once added, it would render as follows. ![Theoretically Productive](https://img.shields.io/badge/THEORETICALLY-PRODUCTIVE-blueviolet) Another option for generating a simple static badge is [For the Badge](https://forthebadge.com/generator/). ![](https://cdn-learn.adafruit.com/assets/assets/000/112/620/medium800/programming_GFP_for_the_badge_header.png?1656183490) You can customise the text for both halves of the badge, as well as the text and background color. Then you are given the option to download the badge as an SVG, or copy the Markdown code necessary to embed it in your profile. To add a badge from this site, you'd design it, click **Copy Markdown \<\>** , and paste it into your profile page where you'd like the badge to show up. The Markdown for their badges is too lengthy to include in this guide. Here is an example personally generated badge rendered. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/623/medium800/programming_GFP_For_the_Badge_theoretically-productive.png?1656189060) There are options beyond these two sites to find existing badges and customise your own badges. You're not limited by the options highlighted above! # Create an Excellent GitHub Profile with Markdown ## Stat Streak and Trophies GitHub provides information about your GitHub activity on the main page of your account by covering basic metrics. It's an excellent way to view your activity in a couple of different ways. However, it only covers your contributions by the numbers. What if you're wondering about your contribution streaks, or more interested in where you're at in terms of others on GitHub? This page has you covered. User [DenverCoder1](https://github.com/DenverCoder1) on GitHub put together the **GitHub** **Readme Streak Stats ** tool to display your activity streak. User [ryo-ma](https://github.com/ryo-ma) put together the **GitHub Profile Trophy ** tool to display your ranking for various statistics on GitHub. These tools each allow you to add a customisable Markdown widget into your README file, that will render on your profile. The documentation on both tools is thorough, so this guide will cover the basics, and link to the tool documentation for more details. ## GitHub Readme Streak Stats ![](https://cdn-learn.adafruit.com/assets/assets/000/112/624/medium800/programming_GFP_streak_stats_header.png?1656190985) The [GitHub Readme Streak Stats](https://github.com/DenverCoder1/github-readme-streak-stats) tool allows you to display your total contributions, your current activity streak, and your longest streak on your GitHub profile. There are two options for getting started with this widget: [Quick setup](https://github.com/DenverCoder1/github-readme-streak-stats#-quick-setup) and [Demo Site](https://github.com/DenverCoder1/github-readme-streak-stats#-demo-site). The [Quick setup](https://github.com/DenverCoder1/github-readme-streak-stats#-quick-setup) allows you to simply use the default settings by providing a line of Markdown where you update the username to your own, and add it to your README. The following is an example of the quick setup Markdown. ```auto ![GitHub Streak](https://github-readme-streak-stats.herokuapp.com/?user=kattni) ``` When included in your profile, it would render something like this. ![GitHub Streak](https://github-readme-streak-stats.herokuapp.com/?user=kattni) The Demo Site section provides a link to the [GitHub Readme Streak Stats Demo site](https://github-readme-streak-stats.herokuapp.com/demo/) that enables you to customise the look of your widget with a live preview. Enter your username at the top. Then, you have the option for basic configuration such as changing to another existing theme, hiding the border, and changing the date format and locale. You can expand the **Advanced Options** section to find the opportunity to fully customise each element of the widget. Regardless of how you do it, you'll want to click **Copy To Clipboard** to get the Markdown for your customised widget. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/628/medium800/programming_GFP_readme_streak_demo_site.png?1656279180) The following is the Markdown for a fully customised widget. ```auto ![GitHub Streak](https://github-readme-streak-stats.herokuapp.com?user=kattni&theme=cobalt&date_format=j%20M%5B%20Y%5D&background=000000&border=7536B2&stroke=9243DD&ring=89502D&fire=FF9554&currStreakNum=D280FF&sideNums=BC52FF&currStreakLabel=64EAE2&sideLabels=48A8A2&dates=A42EE5) ``` It would render into your profile as follows. ![GitHub Streak](https://github-readme-streak-stats.herokuapp.com?user=kattni&theme=cobalt&date_format=j%20M%5B%20Y%5D&background=000000&border=7536B2&stroke=9243DD&ring=89502D&fire=FF9554&currStreakNum=D280FF&sideNums=BC52FF&currStreakLabel=64EAE2&sideLabels=48A8A2&dates=A42EE5) The author makes easy to configure so you can design a widget that matches your style and your profile. Play around with the settings and see what you can make out of it! Check out the [Github Readme Streak Stats README](https://github.com/DenverCoder1/github-readme-streak-stats#-quick-setup) for more details on different ways to use and customise this widget. ## GitHub Profile Trophy ![](https://cdn-learn.adafruit.com/assets/assets/000/112/625/medium800/programming_GFP_GitHub_profile_trophy_header.png?1656192538) The [GitHub Profile Trophy](https://github.com/ryo-ma/github-profile-trophy) tool allows you to display a set of dynamically generated GitHub stats trophies on your profile. There is a [Quick Start](https://github.com/ryo-ma/github-profile-trophy#quick-start) in the documentation that provides Markdown for the default settings for this widget, as well as showing the Markdown for [configuring an optional theme](https://github.com/ryo-ma/github-profile-trophy#use-theme). Further down the page, you'll find a [list of available themes](https://github.com/ryo-ma/github-profile-trophy#apply-theme) including each theme rendered and the URL necessary to enable it. This is the Markdown for the widget with default settings. ```auto ![trophy](https://github-profile-trophy.vercel.app/?username=kattni) ``` It would render in your profile as follows. ![trophy](https://github-profile-trophy.vercel.app/?username=kattni) This is the Markdown if you choose to enable the onedark theme. ```auto ![trophy](https://github-profile-trophy.vercel.app/?username=kattni&theme=onedark) ``` When included in your profile, it would render as follows. ![trophy](https://github-profile-trophy.vercel.app/?username=kattni&theme=onedark) The [documentation for the GitHub Profile Trophy tool](https://github.com/ryo-ma/github-profile-trophy#quick-start) is extensive. In terms of information, it includes what the individual ranks mean, as explaining each element within a single trophy. In terms of configuration, it shows how to filter by various details, how to change the layout, and much more. If you're interested in changing this widget up, check out the docs! # Create an Excellent GitHub Profile with Markdown ## GitHub Metrics GitHub displays some basic metrics on your main account page, including your contributions laid out by year, and a graph of what type of contributions you've made. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/626/medium800/programming_GFP_GitHub_main_account_metrics.png?1656277876) This is an excellent overview, however, there's so much more you can do with your GitHub activity. That's where the following tools come in. There are many options for displaying GitHub metrics using Markdown. This page discusses two popular options for displaying GitHub metrics. GitHub user [anuraghazra](https://github.com/anuraghazra) put together the quick and easy to use **GitHub Readme Stats**. User [lowlighter](https://github.com/lowlighter) built the extensive **Metrics**. The first is simpler and gives you a grade rank for your contributions. The second is far more involved, allows you to configure the widget to include a wide variety of information, and provides an easy setup option. ## GitHub Readme Stats ![](https://cdn-learn.adafruit.com/assets/assets/000/112/627/medium800/programming_GFP_GItHub_Readme_Stats_header.png?1656278941) The [GitHub Readme Stats](https://github.com/anuraghazra/github-readme-stats) tool allows you to add dynamically generated GitHub stats to your profile. The documentation is thorough and covers how to apply all the available configurations to your stats card. It begins with providing the basic Markdown you need to include the default themed stats card in your profile. You'll need to update the code with your username for it to display your stats. The following is an example of the Markdown needed to include the default themed card with no icons. ```auto ![Kattni's GitHub stats](https://github-readme-stats.vercel.app/api?username=kattni) ``` This is how the above Markdown would render in your profile. ![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=kattni) Likely the most popular configuration option would be to include the icons and add a theme. The Markdown to apply a theme (which includes showing the icons) is available on the [main documentation page](https://github.com/anuraghazra/github-readme-stats#themes), and on its own [Available Themes page](https://github.com/anuraghazra/github-readme-stats/blob/master/themes/README.md#available-themes). Here is the Markdown to apply the **tokyonight** theme. ```auto ![Kattni's GitHub stats](https://github-readme-stats.vercel.app/api?username=kattni&theme=tokyonight&show_icons=true) ``` The Markdown above would render as follows in your profile. ![Kattni's GitHub stats](https://github-readme-stats.vercel.app/api?username=kattni&theme=tokyonight&show_icons=true) The [Available Themes page](https://github.com/anuraghazra/github-readme-stats/blob/master/themes/README.md#available-themes) lists all of the available builtin themes for GitHub Readme Stats, including example cards so you know exactly what the theme looks like. For more information, including what the rankings mean and configuring more of it yourself, read through [the main documentation](https://github.com/anuraghazra/github-readme-stats#github-stats-card). ## Metrics ![](https://cdn-learn.adafruit.com/assets/assets/000/112/629/medium800/programming_GFP_Metrics_header.png?1656281752) The [Metrics](https://github.com/lowlighter/metrics) tool generates dynamic metrics that can be embedded in your GitHub profile README. There are [a staggering number of plugins and options](https://github.com/lowlighter/metrics#-customizable-with-40-plugins-and-262-options) to include in this widget. It's important to note that feature availability is based on how you choose to set up Metrics. There are [five ways to set up Metrics](https://github.com/lowlighter/metrics#-setup). Four of them provide access to all of the features. However, they are more advanced and require knowledge in various areas that many folks do not have. You're welcome to check them out, and if they're in your wheelhouse, consider trying them out. The simplest way, which is what will be covered in this section, is to visit a website that allows you to configure the widget with a dynamic preview. This method does not require any local or remote set up, but it only allows access to a limited feature set. To begin, visit the [Metrics configuration site](https://metrics.lecoq.io/). The widget defaults to a set of base content. The preview initially shows placeholder information. ![](https://cdn-learn.adafruit.com/assets/assets/000/112/630/medium800/programming_GFP_Metrics_default_info_on_config_site.png?1656282978) To update to your information, you'll enter your GitHub username in the box on the top of the left sidebar, and click **Generate your metrics!**. You can test this out with the default info by adding your username and clicking the button. Info: ![](https://cdn-learn.adafruit.com/assets/assets/000/112/631/medium800/programming_GFP_Metrics_initial_config_generated.png?1656283100) Now, you can begin adding more sections to your widget. In the left sidebar, you'll find the **Additional Plugins** section that contains subsections, each with a list of plugins preceded by checkboxes. Each time you check a box for a new plugin, the preview will revert to placeholder information, including placeholder info for the newly selected plugin. At any time, you can click the Generate your metrics! button to see your chosen plugins rendered with your GitHub info. Simply be aware, if you change the included plugins by adding or removing, it will once again revert to placeholder info. Warning: If you try to include an unavailable plugin, a warning will appear under the Generate your metrics! button letting you know which unavailable plugins you attempted to add. If you check more than one unavailable plugin, they will all be listed in the same warning. You will not be able to click the Generate button as long as an unavailable plugin is checked. Read through the list, and see what interests you. If you're uncertain what a particular plugin displays, check the box to view it in the preview. You can always remove it if it's not something you're interested. There are so many available, you should definitely be able to generate a collection of information that fits and represents you. As you're going through, you can generate your metrics at any time. You should always click **Generate your metrics!** before copying the provided Markdown from the **Markdown code** tab. This ensures your user information is populated into the Markdown configuration code. The following is the Markdown code for including the base content, most used languages, achievements, and notable contributions. ```auto ![Metrics](https://metrics.lecoq.io/kattni?template=classic&languages=1&achievements=1¬able=1&base.indepth=false&base.hireable=false&languages.limit=8&languages.threshold=0%25&languages.other=false&languages.colors=github&languages.sections=most-used&languages.indepth=false&languages.analysis.timeout=15&languages.categories=markup%2C%20programming&languages.recent.categories=markup%2C%20programming&languages.recent.load=300&languages.recent.days=14&achievements.threshold=C&achievements.secrets=true&achievements.display=detailed&achievements.limit=0¬able.from=organization¬able.repositories=false¬able.indepth=false¬able.types=commit&config.timezone=America%2FNew%20York) ``` The above Markdown would render into your profile as follows. ![Metrics](https://metrics.lecoq.io/kattni?template=classic&languages=1&achievements=1&notable=1&base.indepth=false&base.hireable=false&languages.limit=8&languages.threshold=0%25&languages.other=false&languages.colors=github&languages.sections=most-used&languages.indepth=false&languages.analysis.timeout=15&languages.categories=markup%2C%20programming&languages.recent.categories=markup%2C%20programming&languages.recent.load=300&languages.recent.days=14&achievements.threshold=C&achievements.secrets=true&achievements.display=detailed&achievements.limit=0&notable.from=organization&notable.repositories=false&notable.indepth=false&notable.types=commit&config.timezone=America%2FNew%20York) For full information on all plugins and options available, setup options available, and a list of plugins with links to details and configuration about each plugin, check out the [Metrics documentation](https://github.com/lowlighter/metrics#-metrics-). ## Related Guides - [How to Add a New Board to WipperSnapper](https://learn.adafruit.com/how-to-add-a-new-board-to-wippersnapper.md) - [Working with Multiple Same Address I2C Devices](https://learn.adafruit.com/working-with-multiple-i2c-devices.md) - [Using LittlevGL with Adafruit Displays](https://learn.adafruit.com/using-littlevgl-with-adafruit-displays.md) - [Qualia S3 Fireplace](https://learn.adafruit.com/qualia-s3-fireplace.md) - [The Well-Automated Arduino Library](https://learn.adafruit.com/the-well-automated-arduino-library.md) - [Microsoft Teams Mute Button](https://learn.adafruit.com/teams-mute-button.md) - [Getting Started with Custom Extensions for MakeCode](https://learn.adafruit.com/custom-extensions-for-makecode.md) - [Python Virtual Environment Usage on Raspberry Pi](https://learn.adafruit.com/python-virtual-environment-usage-on-raspberry-pi.md) - [Working with I2C Devices](https://learn.adafruit.com/working-with-i2c-devices.md) - [Phyx LANA TNY CH32V203](https://learn.adafruit.com/phyx-lana-tny-ch32v203.md) - [Scratch 3 Walkthrough and Demo](https://learn.adafruit.com/guide-to-scratch-3.md) - [Facial Detection and Recognition with MEMENTO](https://learn.adafruit.com/facial-detection-and-recognition-with-memento.md) - [Sparkle Motion Christmas Tree Lights](https://learn.adafruit.com/sparkle-motion-christmas-tree-lights.md) - [Contribute to Adafruit's Arduino Libraries with Git and GitHub](https://learn.adafruit.com/contribute-to-arduino-with-git-and-github.md) - [Adafruit IO Basics: Digital Input](https://learn.adafruit.com/adafruit-io-basics-digital-input.md)