README.dev.md

GitHub Language Bar

Features

TODO

Wanna add one to you profile?

Just two steps, two minutes! ⏱

1. Go to your repository and create a workflow file named language_bar.yml under .github/workflows folder. Paste the following content inside:

   name: GitHub Language Bar
   
   on:
     push:               # Run every time config or README changes
       paths:
         - README.md
         - .github/workflows/*
     schedule:           # Run every day at to 4:38 AM
       - cron: 38 4 * * *
     workflow_dispatch:  # Run with a button in the Actions tab
   
   jobs:
     language_bar:
       name: Create GitHub Language Bar
       runs-on: ubuntu-latest
       steps:
         - name: Create Language Bar
           uses: npanuhin/GitHub-Language-Bar@master

2. Add this mark anywhere in your README¹:

   <!-- Langbar -->

3. You are all set! Your bar should appear in a few seconds.
   

   The next steps are optional, but I suggest enabling private repositories so that people can see your true language usage across all repositories, not just the public ones.

   You can also customize your new language bar in various ways. If you have any questions, don't hesitate to ask!

Enable private repositories

1. Generate a new personal access token with access to all your current and future repositories:

   • Go to https://github.com/settings/personal-access-tokens/new and fill the following fields:
   • Token name: whatever you like, e.g. Language-Bar-token
   • Expiration: No Expiration ⚠
   • Repository access: All repositories ⚠
   • Permissions: open up Repository permissions:
     • Contents: set to Read-only
     • Metadata: set to Read-only
   • Scroll all the way down and click Generate token
   • Finally, copy the generated token to the clipboard

2. Add this token to your repository:

   1. Go to the repository, where the target README.md file is located
   2. Open up the repository settings
   3. On the left side select Secrets and Variables -> Actions
   4. Click on New repository secret
      • Name: exactly LANG_BAR_PAT
      • Secret: Paste the copied in the previous step token from the clipboard
      • Click Add secret

3. Add the following parameter to the workflow file (.github/workflows/language_bar.yml):

   steps:
     - name: Create Language Bar
       uses: npanuhin/GitHub-Language-Bar@master
   +   with:
   +     gh_token: ${{ secrets.LANG_BAR_PAT }}  # Token is used to fetch private repositories

   All together it should look like this

   name: GitHub Language Bar
   
   on:
     push:               # Run every time config or README changes
       paths:
         - README.md
         - .github/workflows/*
     schedule:           # Run every day at to 4:38 AM
       - cron: 38 4 * * *
     workflow_dispatch:  # Run with a button in the Actions tab
   
   jobs:
     language_bar:
       name: Create GitHub Language Bar
       runs-on: ubuntu-latest
       steps:
         - name: Create Language Bar
           uses: npanuhin/GitHub-Language-Bar@master
           with:               # Token is used to fetch private repositories
             gh_token: ${{ secrets.LANG_BAR_PAT }}

Warning

If you enable private repositories, the script will collect and log some information about them. Since your profile repository is almost always public, everyone can see your README source and workflow logs (Actions tab). By default, apart from the bar itself, others cannot learn anything about your private repositories. However, be careful when using additional settings:

• If log is turned on: number of bytes per language for each repository is logged
• If you use replace or hide options in the repo:lang format, be aware that the repository name is visible to everyone. All settings are also logged. However, logs can be deleted from the Actions tab (be aware of scheduled runs)

Note

To disable private repositories, just remove or comment out the added lines

Customize

Customizing GitHub Language Bar is simple — just add the parameter you want after ?, as if it was a url: Langbar?key=param

• Include forks: include_forks = yes/no² (default: no)

  Whether to include forked repositories or not

  Example: <!-- Langbar?include_forks=yes -->

• Include collaborative repositories: include_collaborative = yes/no² (default/recommended: no)

  Whether to include repositories that you don't own but have access to as a collaborator. Works only when private repositories are enabled

  Example: <!-- Langbar?include_collaborative=yes -->

  $${\color{ProcessBlue}ⓘ\ \text{Note}}$$
  Not a contributor — collaborator! I can not count contributions yet(

• Replace language: replace=language1->language1_new,repo2:language2->language2_new

  Option to replace the desired language with another language in all repositories or only in a specific repository (comma-separated list)

  Example: <!-- Langbar?replace=Hack->PHP,npanuhin/MyRepo:Hack->PHP -->

• Hide language: hide=language1,repo2:language2,language3

  Option to hide the desired language in all repositories or only in a specific repository (comma-separated list)

  Example: <!-- Langbar?hide=Jupyter Notebook,npanuhin/MyRepo:JavaScript -->

`

Example of all settings combined:

<!-- Langbar?include_forks=yes&include_collaborative=yes&hide=Jupyter Notebook,npanuhin/MyRepo:JavaScript -->

Note

Settings are applied in the order they appear in this list. For example, hide is always applied after replace

Logging

If you want to see the number of bytes of each language in each repository (to get an idea of which setting is best to apply) , you can use the log parameter. Be mindful of your privacy!

steps:
  - name: Create Language Bar
    uses: npanuhin/GitHub-Language-Bar@master
+   with:
+     log: true

After the GitHub Action completes, the log will be at {your_repo_url}/blob/language-bar/log.txt.
For example: https://github.com/npanuhin/npanuhin/blob/language-bar/log.txt

Pro tips

1. As in URLs, individual settings can be used multiple times. For example:
   <!-- Langbar?hide=Jupyter Notebook&hide=npanuhin/MyRepo:JavaScript -->
   is equal to the previous hide example

2. If you want to add a bar to a file other than /README.md, you can specify its path in the readme_path parameter (without leading slash):

       steps:
     - name: Create Language Bar
       uses: npanuhin/GitHub-Language-Bar@master
   +   with:
   +     readme_path: 'path/to/my/awesome/README.md'

Contributing

For technical details and TODO list see contribution guide

Footnotes

1. Actually, it should be on a separate line ↩

2. YeS, 1, true, on, etc. are treated as yes, otherwise as no ↩ ↩²