Add annotations docs

2 files changed, 144 insertions, 0 deletions

diff --git a/git.sr.ht/annotations.md b/git.sr.ht/annotations.md
new file mode 100644
index 0000000..ba19e90
--- /dev/null
+++ b/git.sr.ht/annotations.md
@@ -0,0 +1,139 @@
+---
+title: git.sr.ht annotations reference
+---
+
+Annotations are a feature of git.sr.ht which allows you to upload arbitrary
+*annotations* to files in your source code, which will then be shown on the web.
+An example repo with annotations configured is
+[~sircmpwn/scdoc](https://git.sr.ht/~sircmpwn/scdoc), where they are used to
+link C function calls to their definitions.
+
+To add annotations to your repo, you'll need to have a builds.sr.ht [set
+up](https://man.sr.ht/tutorials/getting-started-with-builds.md), and find an
+annotation generator for your project's programming language(s):
+
+- C: [annotatec](https://git.sr.ht/~sircmpwn/annotatec)
+
+If your language isn't listed here, see [writing custom
+annotators](#writing-custom-annotators).
+
+See each annotator's instructions for generating the annotation file. You'll
+then need to add an OAuth token to builds.sr.ht - go to your [oauth
+settings](https://meta.sr.ht/oauth) and generate a personal access token, then
+paste the generated token into [builds.sr.ht
+secrets](https://builds.sr.ht/secrets) like this:
+
+```sh
+#!/bin/sh
+oauth_token=# your oauth token here
+curl -X PUT \
+    -H "Authorization: token $oauth_token" \
+    -H "Content-Type: application/json" \
+    -d @"$1" \
+    https://git.sr.ht/api/"~$2"/repos/"$3"/annotate
+```
+
+Set the path to `~/upload-annotations` and the file mode to 755, then add the
+UUID to the secrets list in your build manifest. Call the annotator to generate
+annotations for your code, then use the secret script to upload them. The result
+will look something like this:
+
+```
+# ...
+secrets:
+- your-uuid-here
+tasks:
+# ...
+- annotate: |
+    cd your-project
+    find . -name "*.c" | xargs annotatec -g > annotations.json
+    ../upload-annotations annotations.json your-username your-reponame
+```
+
+## Writing custom annotators
+
+The annotations.json format is a mapping of blob IDs to annotations. The blob ID
+is the ID of the blob which the annotations supplement, you can find it for a
+given file like so:
+
+    git ls-tree HEAD path/to/file.c
+
+When writing an annotator, you may find it useful to add the `-r` flag to scan
+the entire git tree at once, and `-z` to make the output more easily machine
+readable. See [`git-ls-tree(1)`](https://git-scm.com/docs/git-ls-tree) for
+details on this command.
+
+Once you have the blob ID, you can specify a list of annotations. Each
+annotation must have a `type`, which can be one of the following:
+
+### "type": "link"
+
+This annotates your code with a link, either an external link or a link to
+another part of your source code.
+
+```json
+{
+  "type": "link",
+  "lineno": integer,
+  "colno": integer,
+  "len": integer,
+  "to": "url...",
+  "title": "anchor title attribute" (optional)
+}
+```
+
+If `to` is a relative URL, it will be assumed to be a link to another part of
+this repository's source tree. Otherwise it's used-as is, for example as a link
+to some external documentation.
+
+### "type": "markdown"
+
+A markdown annotation adds an expandable annotation to the end of the annotated
+line, which when clicked, shows an arbitrary markdown snippet.
+
+```json
+{
+  "type": "markdown",
+  "lineno": integer,
+  "title": "title of the annotation",
+  "content": "markdown text..."
+}
+```
+
+## Full example
+
+Here is a complete example of a valid annotations JSON:
+
+```json
+{
+  "98bc0394a2f15171fb113acb5a9286a7454f22e7": [
+    {
+      "type": "markdown",
+      "lineno": 33,
+      "title": "2 references",
+      "content": "- [../main.c:123](https://example.org)\n- [../main.c:321](https://example.org)"
+    },
+    {
+      "type": "link",
+      "lineno": 38,
+      "colno": 7,
+      "len": 15,
+      "to": "#L6"
+    },
+    {
+      "type": "link",
+      "lineno": 34,
+      "colno": 13,
+      "len": 11,
+      "to": "src/utf8_encode.c#L5"
+    },
+    {
+      "type": "link",
+      "lineno": 41,
+      "colno": 2,
+      "len": 11,
+      "to": "src/utf8_encode.c#L5"
+    }
+  ]
+}
+```
diff --git a/git.sr.ht/index.md b/git.sr.ht/index.md
index a3407d0..0cbae4d 100644
--- a/git.sr.ht/index.md
+++ b/git.sr.ht/index.md
@@ -56,6 +56,11 @@ who has the link, but are not shown in your profile or in search results.
 Private repositories are only visible to you and other logged-in users who you
 explicitly [grant access to](#access).
 
+## Source code annotations
+
+You can generate annotations for your source code to display on git.sr.ht. For
+more information [see this document](annotations.md).
+
 ## Settings
 
 Each repository's settings may be accessed via the settings link on the