Your personal markdown scribe with template-engine and Git(Hub) & RSS powers 📜
You can run markscribe as a GitHub Action: readme-scribe
Render a template to stdout:
markscribe template.tpl
Render to a file:
markscribe -write /tmp/output.md template.tpl
If you use Brew, you can simply install the package:
brew install charmbracelet/tap/markscribe
Or download a binary from the releases page. Linux (including ARM) binaries are available, as well as Debian and RPM packages.
Alternatively you can also build markscribe from source. Make sure you have a
working Go environment (Go 1.16 or higher is required). See the
install instructions.
To install markscribe, simply run:
go get github.com/charmbracelet/markscribe
You can find an example template to generate a GitHub profile README under
templates/github-profile.tpl. Make sure to fill in (or remove) placeholders,
like the RSS-feed or social media URLs.
Rendered it looks a little like my own profile page: https://github.com/charmbracelet
{{range rss "https://domain.tld/feed.xml" 5}}
Title: {{.Title}}
URL: {{.URL}}
Published: {{humanize .PublishedAt}}
{{end}}
{{range recentContributions 10}}
Name: {{.Repo.Name}}
Description: {{.Repo.Description}}
URL: {{.Repo.URL}})
Occurred: {{humanize .OccurredAt}}
{{end}}
This function requires GitHub authentication with the following API scopes:
repo:status, public_repo, read:user.
{{range recentPullRequests 10}}
Title: {{.Title}}
URL: {{.URL}}
State: {{.State}}
CreatedAt: {{humanize .CreatedAt}}
Repository name: {{.Repo.Name}}
Repository description: {{.Repo.Description}}
Repository URL: {{.Repo.URL}}
{{end}}
This function requires GitHub authentication with the following API scopes:
repo:status, public_repo, read:user.
{{range recentStars 10}}
Name: {{.Repo.Name}}
Description: {{.Repo.Description}}
URL: {{.Repo.URL}})
Stars: {{.Repo.Stargazers}}
{{end}}
This function requires GitHub authentication with the following API scopes:
repo:status, public_repo, read:user.
{{range recentCreatedRepos "charmbracelet" 10}}
Name: {{.Name}}
Description: {{.Description}}
URL: {{.URL}})
Stars: {{.Stargazers}}
{{end}}
This function requires GitHub authentication with the following API scopes:
repo:status, public_repo, read:user or read:org if you provide an organization name.
{{range popularRepos "charmbracelet" 10}}
Name: {{.Name}}
NameWithOwner: {{.NameWithOwner}}
Description: {{.Description}}
URL: {{.URL}})
Stars: {{.Stargazers}}
{{end}}
This function requires GitHub authentication with the following API scopes:
read:org, public_repo, read:user
Tip
Use {{with repo "charmbracelet .Name"}} to create a pipeline that grabs additional information about the repo including releases.
{{with repo "charmbracelet" "markscribe"}}
Name: {{.Name}}
Description: {{.Description}}
URL: {{.URL}}
Stars: {{.Stargazers}}
Is Private: {{.IsPrivate}}
Last Git Tag: {{.LastRelease.TagName}}
Last Release: {{humanize .LastRelease.PublishedAt}}
{{end}}
{{range recentRepoReleases "charmbracelet" "markscribe" 10}}
Name: {{.Name}}
Git Tag: {{.TagName}}
URL: {{.URL}}
Published: {{humanize .PublishedAt}}
CreatedAt: {{humanize .CreatedAt}}
IsPreRelease: {{.IsPreRelease}}
IsDraft: {{.IsDraft}}
IsLatest: {{.IsLatest}}
{{end}}
This function requires GitHub authentication with the following API scopes:
repo:status, public_repo, read:user.
{{range recentForkedRepos "charmbracelet" 10}}
Name: {{.Name}}
Description: {{.Description}}
URL: {{.URL}})
Stars: {{.Stargazers}}
{{end}}
This function requires GitHub authentication with the following API scopes:
repo:status, public_repo, read:user or read:org if you provide an organization name.
{{range latestReleasedRepos "charmbracelet" 10}}
Name: {{.Name}}
Description: {{.Description}}
URL: {{.URL}})
Stars: {{.Stargazers}}
Last Release Name: {{.LastRelease.TagName}}
Last Release URL: {{.LastRelease.URL}}
Last Release Date: {{humanize .LastRelease.PublishedAt}}
{{end}}
This function requires GitHub authentication with the following API scopes:
repo:status, public_repo, read:user, read:org.
{{range recentReleases 10}}
Name: {{.Name}}
Git Tag: {{.LastRelease.TagName}}
URL: {{.LastRelease.URL}}
Published: {{humanize .LastRelease.PublishedAt}}
{{end}}
This function requires GitHub authentication with the following API scopes:
repo:status, public_repo, read:user.
{{range recentPushedRepos "charmbracelet" 10}}
Name: {{.Name}}
URL: {{.URL}}
Description: {{.Description}}
Stars: {{.Stargazers}}
{{end}}
This function requires GitHub authentication with the following API scopes:
public_repo, read:org.
Tip
Use {{with repo "charmbracelet .Name"}} to create a pipeline that grabs additional information about the repo including releases.
{{range gists 10}}
Name: {{.Name}}
Description: {{.Description}}
URL: {{.URL}}
Created: {{humanize .CreatedAt}}
{{end}}
This function requires GitHub authentication with the following API scopes:
repo:status, public_repo, read:user.
{{range followers 5}}
Username: {{.Login}}
Name: {{.Name}}
Avatar: {{.AvatarURL}}
URL: {{.URL}}
{{end}}
This function requires GitHub authentication with the following API scopes:
read:user.
{{range sponsors 5}}
Username: {{.User.Login}}
Name: {{.User.Name}}
Avatar: {{.User.AvatarURL}}
URL: {{.User.URL}}
Created: {{humanize .CreatedAt}}
{{end}}
This function requires GitHub authentication with the following API scopes:
repo:status, public_repo, read:user, read:org.
{{range goodReadsReviews 5}}
- {{.Book.Title}} - {{.Book.Link}} - {{.Rating}} - {{humanize .DateUpdated}}
{{- end}}
This function requires GoodReads API key!
{{range goodReadsCurrentlyReading 5}}
- {{.Book.Title}} - {{.Book.Link}} - {{humanize .DateUpdated}}
{{- end}}
This function requires GoodReads API key!
{{range literalClubCurrentlyReading 5}}
- {{.Title}} - {{.Subtitle}} - {{.Description}} - https://literal.club/_YOUR_USERNAME_/book/{{.Slug}}
{{- range .Authors }}{{ .Name }}{{ end }}
{{- end}}
This function requires a LITERAL_EMAIL and LITERAL_PASSWORD.
{{ wakatimeData.HumanReadableTotal }}
This function requires a WAKATIME_API_KEY and potentialy a WAKATIME_URL.
{{ range wakatimeData.Languages | chunk 5 | first }}
- {{ .Name }}: {{ .Percent }}%
{{- end}}
This function requires a WAKATIME_API_KEY and potentialy a WAKATIME_URL.
{{ wakatimeData.Languages | wakatimeCategoryBar 5 }}
TypeScript 5h 6m 42s █░░░░░░░░░░░░░░░░░░░░░░░░ 45.56%
Go 3h 18m 11s █░░░░░░░░░░░░░░░░░░░░░░░░ 29.44%
Astro 53m 35s █░░░░░░░░░░░░░░░░░░░░░░░░ 7.96%
Markdown 31m 42s █░░░░░░░░░░░░░░░░░░░░░░░░ 4.71%
Bash 25m 51s █░░░░░░░░░░░░░░░░░░░░░░░░ 3.84%
This can also be done with Categories, Projects, Editors, OperatingSystems, Machines, and Dependencies
You can also do a double bar
{{ wakatimeDoubleCategoryBar "💾 Languages:" wakatimeData.Languages "💼 Projects:" wakatimeData.Projects 5 }}
💾 Languages:
HTML 5h 43m 12s ███████░░░░░░░░░░░░░░░░░░ 26.46%
TypeScript 5h 4m 48s ██████░░░░░░░░░░░░░░░░░░░ 23.50%
Java 3h 41m 50s █████░░░░░░░░░░░░░░░░░░░░ 17.10%
Markdown 2h 25m 44s ███░░░░░░░░░░░░░░░░░░░░░░ 11.23%
CSS 1h 4m 51s ██░░░░░░░░░░░░░░░░░░░░░░░ 5.00%
💼 Projects:
unduck 7h 33m 35s █████████░░░░░░░░░░░░░░░░ 34.96%
2025-reefscape 3h 53m 7s █████░░░░░░░░░░░░░░░░░░░░ 17.97%
unknown 3h 45m 28s █████░░░░░░░░░░░░░░░░░░░░ 17.38%
zera 2h 54m 57s ████░░░░░░░░░░░░░░░░░░░░░ 13.48%
hackatime-bot 1h 9m 48s ██░░░░░░░░░░░░░░░░░░░░░░░ 5.38%
This function requires a WAKATIME_API_KEY and potentialy a WAKATIME_URL.
You can find the full list of the data you can get at wakatimeTypes.go
This function requires a WAKATIME_API_KEY and potentialy a WAKATIME_URL.
markscribe uses Go's powerful template engine. You can find its documentation here: https://golang.org/pkg/text/template/
markscribe comes with sprout and a few more template helpers:
To format timestamps, call humanize:
{{humanize .Timestamp}}
To limit the length of an array
{{.Array | chunk 5 | first}}
In order to access some of GitHub's API, markscribe requires you to provide a
valid GitHub token in an environment variable called GITHUB_TOKEN. You can
create a new token by going to your profile settings:
Developer settings > Personal access tokens > Generate new token
In order to access some of GoodReads' API, markscribe requires you to provide a
valid GoodReads key in an environment variable called GOODREADS_TOKEN. You can
create a new token by going here.
Then you need to go to your repository and add it, Settings -> Secrets -> New secret.
You also need to set your GoodReads user ID in your secrets as GOODREADS_USER_ID.
In order to access any wakatime data you need to provide your api key as WAKATIME_API_KEY. If you use an
alternative wakatime server such as wakapi
or hackatime then export the base wakatime compatible route as WAKATIME_URL e.g. https://waka.hackclub.com/api/compat/wakatime/v1/.
Q: That's awesome, but can you expose more APIs and data?
A: Of course, just open a new issue and let me know what you'd like to do with markscribe!
Q: That's awesome, but I don't have my own server to run this on. Can you help?
A: Check out readme-scribe, a GitHub Action that runs markscribe for you!