Getting started

Set up your gist.id profile. About 30 minutes if you edit the markdown yourself, or 10 minutes plus a 24-hour wait if you import from LinkedIn.

A gist.id profile is a public GitHub repository named gist-id, containing your CV as a handful of markdown files. When you push, the repo builds a signed feed.postcard and publishes it via GitHub Pages. Visiting gist.id/<your-handle> renders that feed as a profile page.

Verification is part of the build: programming-language skills you claim are checked against your public GitHub activity. The matched skills show a ✓ evidence link to the actual repos. Claims without evidence still appear; they just don't get the badge.

Step 1 — Create your repository

Open github.com/gist-id/template and click Use this template → Create a new repository.

• Owner: your personal account (unless you want the profile to belong to an organisation).
• Repository name: gist-id. This is mandatory — the URL gist.id/<handle> resolves to <handle>.github.io/gist-id/.
• Public. Your profile is fully public. Don't put anything in it you wouldn't want indexed by search engines or LLMs.

Step 2 — Generate a signing key

Each feed is signed with an ed25519 key so the network can verify its authenticity. Download the builder binary with whichever tool you have installed.

With gh (GitHub CLI):

gh release download --repo gist-id/gist-id \
  --pattern 'gist-id-x86_64-linux.tar.gz'
tar -xzf gist-id-x86_64-linux.tar.gz

With curl:

TAG=$(curl -s https://api.github.com/repos/gist-id/gist-id/releases/latest \
  | grep '"tag_name"' | cut -d'"' -f4)
curl -sLO "https://github.com/gist-id/gist-id/releases/download/$TAG/gist-id-x86_64-linux.tar.gz"
curl -sLO "https://github.com/gist-id/gist-id/releases/download/$TAG/gist-id-x86_64-linux.tar.gz.sha256"
sha256sum -c gist-id-x86_64-linux.tar.gz.sha256
tar -xzf gist-id-x86_64-linux.tar.gz

Then generate a key:

./gist-id keygen

The output is a base64-encoded private key. In your new repo, go to Settings → Secrets and variables → Actions → New repository secret. Add:

• Name: GIST_ID_SIGNING_KEY
• Value: the key

Step 3 — Enable GitHub Pages

On your new repo: Settings → Pages. Set Source to GitHub Actions. The build workflow does the rest on first push.

Step 4 — Add the gist-id topic

On your repo's main page, click the gear icon next to About. In the Topics field, add gist-id. This is how the discovery index finds your profile and lists you under gist.id/?tag=<skill> pages.

Step 5 — Add your content

Pick one path. The end result is the same; only the starting point differs.

Path A — Edit markdown directly

The template repo ships with example markdown files. Edit them in place via the GitHub web UI or by cloning the repo locally:

• profile.md — name, headline, location, links, bio.
• resume/work.md — work history.
• resume/education.md — education.
• resume/skills.md — skill categories and skills. Use clean single-skill names (Rust, not C/C++/VB) for verification.
• resume/projects.md — projects.
• resume/patents.md — patents (if any).
• posts/*.md — longer writing (optional).

Each file's structure is straightforward. See an example at FigmentEngine/gist-id.

Path B — Import from LinkedIn

LinkedIn lets you export your data. The CV-relevant CSVs (positions, education, projects, patents) are only in the full archive, which takes around 24 hours.

Request the export:

1. LinkedIn → Settings & Privacy → Data privacy → Get a copy of your data.
2. Choose Download larger data archive (the first option, not the category-picker).
3. Click Request archive. LinkedIn emails you within 24 hours with a download link, valid for 72 hours.

You can do steps 1–4 above while you wait. When the email arrives, download the ZIP, then get the importer (skip if you have it from Step 2):

With gh:

gh release download --repo gist-id/gist-id \
  --pattern 'gist-id-x86_64-linux.tar.gz'
tar -xzf gist-id-x86_64-linux.tar.gz

With curl:

TAG=$(curl -s https://api.github.com/repos/gist-id/gist-id/releases/latest \
  | grep '"tag_name"' | cut -d'"' -f4)
curl -sLO "https://github.com/gist-id/gist-id/releases/download/$TAG/gist-id-x86_64-linux.tar.gz"
tar -xzf gist-id-x86_64-linux.tar.gz

The importer reads an unzipped archive directory, not the .zip file:

# Unzip the LinkedIn export
unzip ~/Downloads/Complete_LinkedInDataExport_*.zip -d linkedin-export

# Clone your profile repo locally
git clone git@github.com:<your-handle>/gist-id
cd gist-id

# Import — must be run from inside the repo (it looks for
# the .gist-id-template marker file in the current directory)
../gist-id import ../linkedin-export

Review the generated profile.md, resume/work.md, resume/education.md, resume/projects.md, resume/patents.md, plus any imported posts/*.md from your LinkedIn articles. Expect to fix capitalisation, dates, and descriptions that LinkedIn stored badly.

The importer does not produce resume/skills.md. LinkedIn's skill data is noisy and partly autogenerated; write your skills file by hand. Use clean single-language names so verification can match against your public repos.

Step 6 — Push and verify

Commit and push. The build workflow runs automatically. On the Actions tab you should see it succeed in about a minute. Then give Pages another minute to deploy.

Visit:

https://gist.id/<your-github-handle>

Your profile is live. It rebuilds every 6 hours automatically, picking up new verification data from your public GitHub activity. Push any time to rebuild immediately.

Updating your profile

Edit the markdown files, push. The build is idempotent and signed. Your URL never changes.

The discovery indexer crawls every 6 hours. New tags you claim (with verified evidence) appear in gist.id/?tag=<skill> on the next crawl.

What gets verified

Programming-language skills are verified against your public GitHub repository activity. The build checks:

• Your own non-fork public repos.
• Repos in any organisation where you've pushed in the last 90 days.

For each, the language byte breakdown is fetched. If a language matches a skill name (case-insensitive), the skill gets a ✓ evidence badge linking to the repo with the most bytes in that language.

Non-language skills (frameworks, databases, soft skills) are shown as claims, without verification. Honest about scope: gist.id verifies what's publicly observable on GitHub.

How discovery works

The indexer searches GitHub for repos with the gist-id topic and named gist-id. It fetches and verifies each profile's signed feed, then writes per-tag index files served at gist-id.github.io/index.

Only verified claims appear in tag pages. Someone claiming Rust with no public Rust code stays on their own profile but doesn't appear under gist.id/?tag=rust. This keeps the discovery index honest.

Troubleshooting

My profile page shows "no gist.id profile found"

Either the repo isn't named gist-id, or Pages isn't enabled, or the first build hasn't finished. Check the Actions tab on your repo.

The build succeeded but I get a 404

GitHub Pages takes 30–60 seconds to deploy after a build. If still 404 after a few minutes, check Settings → Pages on your repo — the source should be GitHub Actions, not a branch.

Skills don't show ✓ evidence

Verification only finds languages with bytes in public repos. If your work is private, there's nothing to verify. Composite names like C/C++/VB can't match GitHub's single-language taxonomy. Split them into C, C++, Visual Basic if you want each verified individually.

I'm not showing up in the discovery index

Make sure the gist-id topic is on your repo (Step 4). The indexer crawls every 6 hours, so allow up to that for new profiles to appear.

I want to rename my GitHub handle

Rename on GitHub. The URL gist.id/<old-handle> will 404 once <old-handle>.github.io no longer resolves. gist.id/<new-handle> works immediately if the repo is still public.

Privacy

Everything in your profile repo is fully public. Don't include things you wouldn't post publicly. Email is optional. There's no account system, no profile-private mode, and no tracking — gist.id stores no data about you beyond what you've published yourself.