readme

package
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 28, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package readme generates GitHub profile README files from user profile data.

Index

Constants

View Source 
const DefaultTemplate = `{{- /* Greeting */ -}}
{{- if .Config.Greeting }}
# {{ .Config.Greeting }}
{{ end }}
{{- /* Bio */ -}}
{{- if .Config.Bio }}
{{ .Config.Bio }}
{{ end }}
{{- /* Current work and learning */ -}}
{{- if or .Config.CurrentWork .Config.Learning }}

{{- if .Config.CurrentWork }}
- {{ .Config.CurrentWork }}
{{- end }}
{{- if .Config.Learning }}
- {{ .Config.Learning }}
{{- end }}
{{ end }}
{{- /* Contribution Heatmap */ -}}
{{- if and .Config.ShowHeatmap .Heatmap }}

## Contribution Activity

` + "```" + `
{{ .Heatmap }}` + "```" + `
{{ end }}
{{- /* GitHub Stats Table */ -}}
{{- if .Config.ShowStats }}

## GitHub Stats

_{{ formatDateRange .Profile.From .Profile.To }}_

| Metric | Value |
|--------|-------|
| Commits | {{ formatNumber .Profile.TotalCommits }} |
| Pull Requests | {{ formatNumber .Profile.TotalPRs }} |
| Issues | {{ formatNumber .Profile.TotalIssues }} |
| Code Reviews | {{ formatNumber .Profile.TotalReviews }} |
| Lines Added | +{{ formatNumber .Profile.TotalAdditions }} |
| Lines Deleted | -{{ formatNumber .Profile.TotalDeletions }} |
{{- if .Profile.Calendar }}
| Longest Streak | {{ .Profile.Calendar.LongestStreak }} days |
{{- end }}
{{ end }}
{{- /* Top Repositories */ -}}
{{- if and .Config.ShowTopRepos (gt (len .TopRepos) 0) }}

## Top Repositories

| Repository | Commits | Lines Changed |
|------------|---------|---------------|
{{- range .TopRepos }}
| [{{ .FullName }}]({{ repoURL .FullName }}) | {{ formatNumber .Commits }} | {{ formatChange .Additions .Deletions }} |
{{- end }}
{{ end }}
{{- /* Organizations */ -}}
{{- if gt (len .Config.Organizations) 0 }}

## Other Projects

{{- range .Config.Organizations }}
- [{{ .Name }}]({{ .URL }}){{ if .Description }} - {{ .Description }}{{ end }}
{{- end }}
{{ end }}
{{- /* Connect Links */ -}}
{{- if hasLinks .Config }}

## Connect

{{ connectLinks .Config }}
{{ end }}
{{- /* External Stats */ -}}
{{- if gt (len .Config.ExternalStats) 0 }}

## Stats

| Platform | Metric | Value |
|----------|--------|-------|
{{- range .Config.ExternalStats }}
| {{ .Platform }} | {{ .Label }} | [{{ .Value }}]({{ .URL }}) |
{{- end }}
{{ end }}
`

DefaultTemplate is the default Go template for README generation. It supports all Config options and gracefully handles missing data.

Variables

View Source 
var HeatmapChars = map[profile.ContributionLevel]rune{
	profile.LevelNone:    '░',
	profile.LevelLow:     '▒',
	profile.LevelMedium:  '▓',
	profile.LevelHigh:    '█',
	profile.LevelMaximum: '█',
}

HeatmapChars maps contribution levels to Unicode block characters.

Functions

func GenerateCompactHeatmap 

func GenerateCompactHeatmap(calendar *profile.ContributionCalendar) string

GenerateCompactHeatmap creates a more compact single-row heatmap. This is useful for inline display in the README.

func GenerateHeatmap 

func GenerateHeatmap(calendar *profile.ContributionCalendar) string

GenerateHeatmap creates an ASCII contribution calendar from calendar data. The output shows a grid with month labels across the top and weekday labels on the left.

Types

type Config 

type Config struct {
	// Bio/greeting section
	Greeting    string `json:"greeting,omitempty"`     // e.g., "Hi there"
	Bio         string `json:"bio,omitempty"`          // Short bio/tagline
	CurrentWork string `json:"current_work,omitempty"` // "Currently working on..."
	Learning    string `json:"learning,omitempty"`     // "Currently learning..."

	// Links section
	Organizations []Organization `json:"organizations,omitempty"` // Other GitHub orgs to highlight
	Blog          *Link          `json:"blog,omitempty"`          // Blog URL
	Website       *Link          `json:"website,omitempty"`       // Personal website
	LinkedIn      *Link          `json:"linkedin,omitempty"`      // LinkedIn profile
	Twitter       *Link          `json:"twitter,omitempty"`       // Twitter/X profile

	// Display options
	ShowStats     bool `json:"show_stats"`      // Show contribution stats table
	ShowTopRepos  bool `json:"show_top_repos"`  // Show top repositories
	ShowLanguages bool `json:"show_languages"`  // Show language breakdown (if available)
	ShowHeatmap   bool `json:"show_heatmap"`    // Show contribution heatmap
	TopReposCount int  `json:"top_repos_count"` // Number of top repos to show (default: 5)

	// External stats placeholders (to be filled by structured-profile)
	ExternalStats []ExternalStat `json:"external_stats,omitempty"` // StackOverflow, blog posts, etc.
}

Config holds static content and display options for README generation.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a Config with sensible defaults.

type ExternalStat 

type ExternalStat struct {
	Platform string `json:"platform"` // "stackoverflow", "blog", etc.
	Label    string `json:"label"`    // "Reputation", "Posts", etc.
	Value    string `json:"value"`    // "15.2k", "42", etc.
	URL      string `json:"url"`      // Link to profile/site
}

ExternalStat represents a stat from an external platform.

type Generator 

type Generator struct {
	Template *template.Template // Custom template (optional)
}

Generator creates README markdown from profile data and config.

func NewGenerator 

func NewGenerator() (*Generator, error)

NewGenerator creates a new README generator with the default template.

func NewGeneratorWithTemplate 

func NewGeneratorWithTemplate(tmpl *template.Template) *Generator

NewGeneratorWithTemplate creates a generator with a custom template.

func (*Generator) Generate 

func (g *Generator) Generate(p *profile.UserProfile, cfg *Config) (string, error)

Generate creates README markdown from profile data and config.

func (*Generator) GenerateToFile 

func (g *Generator) GenerateToFile(p *profile.UserProfile, cfg *Config, path string) error

GenerateToFile writes README markdown to a file. 

type Link struct {
	Text string `json:"text"`
	URL  string `json:"url"`
}

Link represents a hyperlink with display text and URL.

type Organization 

type Organization struct {
	Name        string `json:"name"`        // Display name
	URL         string `json:"url"`         // GitHub URL
	Description string `json:"description"` // Brief description
}

Organization represents a GitHub organization to highlight.

type TemplateData 

type TemplateData struct {
	Profile  *profile.UserProfile
	Config   *Config
	Heatmap  string // Pre-generated ASCII heatmap
	TopRepos []profile.RepoContribution
}

TemplateData contains all data available to the README template.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.