Wiki, gists, Pages, github.dev, Codespaces
Intermediate GitHub UI
Why this matters
Deciding where writing belongs is a daily judgement, and GitHub offers four plausible homes. These are also the features that need no Git knowledge at all, which makes them the easiest way to start contributing.
Which home for which writing
| Put it in | When |
|---|---|
The repository (docs/, README.md) |
It must be reviewed, versioned with the code, and shipped with a release |
| The wiki | It is context on its own schedule: runbooks, onboarding, meeting notes, decisions |
| An issue or discussion | It is about one piece of work or one question |
| A gist | It is a fragment worth sharing that belongs to no repository |
The dividing question for the first two is review: repository content goes through a pull request; wiki edits are saved immediately. If a mistake in the text would be a bug, it belongs in the repository.
The wiki
The Wiki tab, if the repository has it enabled in Settings. Pages are Markdown, the sidebar can be customised with a _Sidebar page, and every edit is recorded.
The part people miss: a wiki is its own Git repository, separate from the code, at the repository's address with .wiki.git on the end:
$ git clone git@github.com:northwind-trails/trailguide.wiki.git
$ cd trailguide.wikiThat matters when you want to write ten pages in your editor or restructure a wiki. Note the consequence: wiki edits do not go through a pull request and are not covered by branch rules, which is what makes them convenient and why product documentation belongs in the repository instead.
Gists
A gist is one or more files with a URL, at gist.github.com. Two visibilities, and the naming is a trap:
| Visibility | Means |
|---|---|
| Public | Listed, searchable, indexed |
| Secret | Not listed and not searchable, but anyone with the link can read it |
Secret is not private. Never put a credential or customer data in a gist, whatever its visibility. Gists are version controlled, can be cloned like any repository, and are ideal for "can you send me that command again?".
Pages
GitHub Pages publishes a static site from a repository, which is how many teams host documentation. Settings → Pages offers two publishing sources:
| Source | How it works |
|---|---|
| Deploy from a branch | GitHub serves the repository root or the /docs folder of a chosen branch, as is |
| GitHub Actions | A workflow builds the site and publishes the result, which is what any site with a build step uses |
The address follows the account: a user site is https://<username>.github.io, and a project site is https://<username>.github.io/<repository>, with custom domains configured on the same page.
What this means for a writer: your documentation is published by merging. A pull request is the preview and review step; the merge is the publication. Worth knowing before asking someone to "put the new page online".
github.dev and Codespaces
Both give you an editor in the browser, and they are very different things.
| github.dev | Codespaces | |
|---|---|---|
| Opened by | Pressing ., or changing the domain to github.dev |
Code → Codespaces → Create codespace |
| Is | An editor with no machine behind it | A full development machine in the cloud |
| Can | Edit, search, commit, open a pull request | Everything, including a terminal, running and debugging the project |
| Starts in | Instantly | A minute or two |
| Costs | Nothing | Free quota, then billed |
Use github.dev for a handful of related edits with no clone at hand: fixing five files after a rename, or applying review comments from a borrowed laptop. Use a codespace when you need to run the project, which is exactly what github.dev cannot do.
How to do it
The wiki and every gist are Git repositories, so they behave normally:
$ git clone git@github.com:northwind-trails/trailguide.wiki.gitEach wiki page is a Markdown file named after its title, so Home.md is the front page. Edit, commit and push; the web wiki updates immediately, with no pull request step.
Clone the wiki like any repository and edit it with Markdown preview open. The GitHub extension can also create a gist from a selection, and a codespace opens in VS Code directly through Remote Explorer.
Clone the wiki as a project for split-pane Markdown preview. JetBrains Gateway can connect to a codespace, so the IDE runs locally against the cloud machine.
The equivalents are a wiki (also a separate Git repository), snippets instead of gists, GitLab Pages built by a CI job, and the Web IDE, also opened with the . key. See lesson 9.11.
- Wiki tab → Create the first page or New page; the page history shows every edit.
- Clone the wiki from its
.wiki.gitaddress when you want to work locally. - + → New gist for a fragment; remember that "secret" means unlisted, not private.
- Settings → Pages to see the publishing source and the site's address.
- Press . on any repository for github.dev, or Code → Codespaces for a machine that can run things.
Common mistakes
- Product documentation in the wiki, where it is unreviewed and drifts from the code.
- Runbooks in the repository that need a pull request to fix a phone number.
- Treating "secret" gists as private. Anyone with the link can read them.
- Assuming the wiki cannot be edited locally. It is a Git repository.
- Expecting github.dev to run the project. That is a codespace.
- Editing the published Pages site. The site is rebuilt from the repository.
Try it yourself
Goal: use each one and notice what it is good at.
- Enable the wiki in Settings and create a page with three lines about your project.
- Clone the wiki from its
.wiki.gitaddress, add a second page locally, push, and refresh. - Create a secret gist with the two commands you use most, and note that its link works signed out.
- Press . on your repository, change two files, and commit them to a new branch from the Source Control panel.
- Note which of these created a pull request and which changed something immediately.
Expected result: a wiki with a page written in the browser and one pushed from your clone, a gist you can share, and a branch created from the browser editor.
Show solution
Only step 4 leads to review. Everything else changes the moment you save, which is the practical difference between the wiki and gists on one side and the repository on the other. Writing that must be right at the moment of a release belongs where review happens.