see generated README.md ↓

Markscribe

Markscribe is a tool that allows you to generate markdown content using templates and interact with GitHub and RSS feeds. It can be run as a GitHub Action and offers various functions like rendering templates, accessing GitHub data, and working with GoodReads API. This is useful if you want to generate a README.md automatically on GitHub. For example you can add things such as: what you are working on,latest projects, recent stars, etc., to your GitHub profile README.

Another good example is HUGO, a static site generator, automatically generates XML files for websites. An example URL would look something like this:
- https://paulius.uk/index.xml

This is useful if you want to add your recent blog posts or posts from another blog site such as Medium.

Template (README.gtpl)

If you don’t have a README.md file for your profile, create a new repository and name it with your username. Then we will need to create a README.gtpl file. This file will contain a template that will allow you to generate content for your README. Additionally, if you already have a README.md, copy all of your existing README.md file into README.gtpl and then add the content you want to be generated.

Here are few Examples that you can add to README.gtpl:

### 📰 Recent Blog Posts
{{ range rss "https://paulius.uk/index.xml" 5 }}
- [{{ .Title }}]({{ .URL }})
{{- end }}

#### 📖 My medium blog posts
{{- range rss "https://yourusername.medium.com/feed" 5 }}
- [{{ .Title }}]({{ .URL }}) ({{ humanize .PublishedAt }})
{{- end }}

### 👷 Check out what I'm currently working on
{{ range recentContributions 5 }}
- [{{ .Repo.Name }}]({{ .Repo.URL }}) - {{ .Repo.Description }}
{{- end }} -->

### 🌱 My latest projects
{{ range recentRepos 5 }}
- [{{ .Name }}]({{ .URL }}) - {{ .Description }}
{{- end }}

### 🔨 My recent Pull Requests
{{ range recentPullRequests 5 }}
- [{{ .Title }}]({{ .URL }}) on [{{ .Repo.Name }}]({{ .Repo.URL }})
{{- end }}

### ⭐ Recent Stars
{{ range recentStars 5 }}
- [{{ .Repo.Name }}]({{ .Repo.URL }}) - {{ .Repo.Description }}
{{- end }}

markscribe docs:
/muesli/markscribe

My GitHub profile Readme structure:
My README structure

GitHub Automation (markscribe.yml & GitHub Actions)

To automate generating README.md, we are going to use GitHub Actions. For this to work, we need to create the following folder structure and file:

• /.github/workflows/markscribe.yml

My markscribe.yml file looks like this:

name: markscribe

on:
  push:
  workflow_dispatch:
  schedule:
    - cron: '* * * * 0'

jobs:
  markscribe:
    permissions:
      contents: write  # Add this line to grant write permission to contents
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v2

      - name: Generate README
        uses: muesli/readme-scribe@master
        env:
          GITHUB_TOKEN: ${{ secrets.GH_PAT }}
        with:
          template: 'README.gtpl'
          writeTo: 'README.md'

      - name: Commit README
        uses: stefanzweifel/git-auto-commit-action@v4
        env:
          GITHUB_TOKEN: ${{ github.token }}
        with:
          commit_message: 'markscribe: update README.md'

markscribe.yml:

Schedule cron

Here, I highlighted cron: '* * * * 0', which basically lets you choose how often you want to generate and update your README. You can fine-tune this to your liking using site Crontab Guru, which allows you to specify whether you want to update it hourly, weekly, monthly, etc.:

Generating GitHub token

Also I highlighted GITHUB_TOKEN: ${{ secrets.GH_PAT }} To generate GitHub token go to:
Account Settings > Developer settings > Personal access tokens > Tokens (classic) > Generate new token ▼ > Generate new token (classic)

Add a Name for the token and tick these boxes:

• workflow
• repo:status
• public_repo
• read:packages
• read:org
• read:user
• gist
• read:project

Even though you could get away with only these checked (repo:status, public_repo, read:user, read:org) see: markscribe docs , I allowed all of them because I also generate GitHub Metrics and will use the same token under Secret (GH_PAT).

Click “generate token”.

Placing GitHub token into Secret

Copy your token and go to:
README repository > Settings > Secrets and variables > Actions > New repository secret

Here paste your generated token under Secret* and name it GH_PAT (You can name it differently, but if you do, don’t forget to update your markscribe.yml file accordingly.).

Lastly, under your README repository Settings select Actions on the left side:
markscribe > Run workflow ▼ > Run workflow

That's it. Now let GitHub Actions and markscribe work their magic, and enjoy automatically generated content!

Final output of README.md

Bottom line

Automating README updates with Markscribe and GitHub Actions streamlines the process of keeping your profile dynamic and informative. With customizable templates and scheduled updates, Markscribe ensures that your README reflects your latest projects and contributions. Embrace the power of automation to effortlessly maintain a vibrant GitHub profile that showcases your work and engages visitors effectively.