markscribe

README

markscribe

Your personal markdown scribe with template-engine and Git(Hub) & RSS powers 📜

Fork

This is a fork of muesli/markscribe.

Usage

Render a template to stdout:

markscribe template.tpl

Render to a file:

markscribe -write /tmp/output.md template.tpl

Diagnostic logs are written to stderr by default. They include template stages, operation timings and result counts, GitHub query shapes and non-secret inputs, each HTTP attempt (including retries), status codes, GitHub request IDs, rate-limit headers, pagination cursors, and contribution/release filtering decisions. GraphQL error messages, extensions, paths, and source locations are also logged, with query IDs connecting queries to their HTTP attempts. GitHub's internal errors may omit the failing field; their request IDs can be provided to GitHub Support. Authorization headers, credentials, raw HTTP bodies, successful response data, and generated Markdown are not logged. Large histories can produce substantial log output.

To save diagnostics separately from the generated Markdown:

markscribe -write README.md templates/README.md.tpl 2>markscribe.log

Installation

To install markscribe, simply run:

go install github.com/crazy-max/markscribe@dev

Templates

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/crazy-max

Functions

RSS feed

{{range rss "https://domain.tld/feed.xml" 5}}
Title: {{.Title}}
URL: {{.URL}}
Published: {{humanize .PublishedAt}}
{{end}}

Your recent contributions

Returns public, non-fork repositories ordered by your latest authored commit on their default branch. Repository discovery paginates your affiliated repositories and repositories from your merged pull requests, then verifies commit authorship. The profile repository is excluded.

{{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.

Your recent pull requests

{{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.

Repositories you recently starred

{{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.

Repositories you recently created

{{range recentRepos 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.

Custom GitHub repository

{{with repo "crazy-max" "markscribe"}}
Name: {{.Name}}
Description: {{.Description}}
URL: {{.URL}}
Stars: {{.Stargazers}}
Is Private: {{.IsPrivate}}
Last Git Tag: {{.LastRelease.TagName}}
Last Release: {{humanize .LastRelease.PublishedAt}}
{{end}}

This function requires GitHub authentication with the following API scopes: repo:status, public_repo, read:user.

Forks you recently created

{{range recentForks 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.

Recent releases you contributed to

Uses the same verified repositories as recent contributions, ordered by release publication date rather than your contribution date. Drafts and prereleases are excluded. Discovery reads all candidate pages using small, separate GraphQL requests to avoid expensive contribution aggregates; large accounts take more requests to render.

Repository and pull-request lists use pages of 100 entries. Completed contribution discovery is reused by both functions during a render, so requesting recent releases does not repeat the repository scan or commit-history lookups. Failed discovery is not cached.

{{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.

Your published gists

{{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.

Your latest followers

{{range followers 5}}
Username: {{.Login}}
Name: {{.Name}}
Avatar: {{.AvatarURL}}
URL: {{.URL}}
{{end}}

This function requires GitHub authentication with the following API scopes: read:user.

Your sponsors

{{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.

Your GoodReads reviews

{{range goodReadsReviews 5}}
- {{.Book.Title}} - {{.Book.Link}} - {{.Rating}} - {{humanize .DateUpdated}}
{{- end}}

This function requires GoodReads API key!

Your GoodReads currently reading books

{{range goodReadsCurrentlyReading 5}}
- {{.Book.Title}} - {{.Book.Link}} - {{humanize .DateUpdated}}
{{- end}}

This function requires GoodReads API key!

Your Literal.club currently reading books

{{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.

Template Engine

markscribe uses Go's powerful template engine. You can find its documentation here: https://golang.org/pkg/text/template/

Template Helpers

markscribe comes with a few handy template helpers:

To format timestamps, call humanize:

{{humanize .Timestamp}}

To reverse the order of a slice, call reverse:

{{reverse (rss "https://domain.tld/feed.xml" 5)}}

GitHub Authentication

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

GoodReads API key

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.

FAQ

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!