A documentation site generator that fits Sourcegraph's needs:
- Markdown source files that are browseable on the file system and readable as plain text (without custom directives or complex front matter or configuration)
- Served by an HTTP server, not generated as static HTML files, to eliminate the need for external static site host configuration (which we found to be error-prone)
- Provides built-in site search for all documentation versions
go get github.com/sourcegraph/docsite/cmd/docsite
docsite -hdocsite check: check for common problems (such as broken links)docsite serve: serve the site over HTTP
To use docsite for docs.sourcegraph.com, see "Documentation site" in the Sourcegraph documentation.
The docsite check command runs various checks on your documentation site to find problems:
- invalid links
- broken links
- disconnected pages (with no inlinks from other pages)
If any problems are found, it exits with a non-zero status code.
To ignore the disconnected page check for a page, add YAML ignoreDisconnectedPageCheck: true to the top matter in the beginning of the .md file. For example:
---
ignoreDisconnectedPageCheck: true
---
# My page title
The site data describes the location of its templates, assets, and content. It is a JSON object with the following properties.
content: a VFS URL for the Markdown content files.contentExcludePattern: a regular expression specifying Markdown content files to exclude.baseURLPath: the URL path where the site is available (such as/or/help/).rootURL: (optional) the root URL (scheme + host). Only used for rare cases where this is absolutely necessary, such as SEO tags fox example.templates: a VFS URL for the Go-style HTML templates used to render site pages.assets: a VFS URL for the static assets referred to in the HTML templates (such as CSS stylesheets).assetsBaseURLPath: the URL path where the assets are available (such as/assets/).redirects: an object mapping URL paths (such as/my/old/page) to redirect destination URLs (such as/my/new/page).check(optional): an object containing a single propertyignoreURLPattern, which is a RE2 regexp of URLs to ignore when checking for broken URLs withdocsite check.search(optional): an object containing a single propretyskipIndexURLPattern, which is a RE2 regexp pattern that if matching any content file URL will remove that file from the search index.
The possible values for VFS URLs are:
-
A relative path to a local directory (such as
../myrepo/doc). The path is interpreted relative to thedocsite.jsonfile (if it exists) or the current working directory (if site data is specified inDOCSITE_CONFIG). -
An absolute URL to a Zip archive (with
httporhttpsscheme). The URL can contain a fragment (such as#mydir/) to refer to a specific directory in the archive.If the URL fragment contains a path component
*(such as#*/templates/), it matches the first top-level directory in the Zip file. (This is useful when using GitHub Zip archive URLs, such ashttps://codeload.github.com/alice/myrepo/zip/myrev#*/templates/. GitHub produces Zip archives with a top-level directory$REPO-$REV, such asmyrepo-myrev, and using#*/templates/makes it easy to descend into that top-level directory without needing to duplicate themyrevin the URL fragment.)If the URL contains the literal string
$VERSION, it is replaced by the user's requested version from the URL (e.g., the URL path/@foo/barmeans the version isfoo).⚠️ If you are using GitHubcodeload.github.comarchive URLs, be sure your URL containsrefs/heads/$VERSION(as inhttps://codeload.github.com/owner/repo/zip/refs/heads/$VERSION), not just$VERSION. This prevents someone from forking your repository, pushing a commit to their fork with unauthorized content, and then crafting a URL on your documentation site that would cause users to view that unauthorized content (which may contain malicious scripts or misleading information).
The templates use Go-style HTML templates.
- Document pages are rendered using a template named
document.html. - Search result pages are rendered using a template named
search.html. - The file
root.html, if it exists, is loaded when rendering any template. You can define common templates in this file.
See the following examples:
In addition to the redirects property in site data, you can also specify redirects in a text file named redirects at the top level of the assets VFS. The format is as follows:
FROM-PATH TO-URL STATUS-CODE
For example:
# Comments are allowed
/my/old/page /my/new/page 308
/another/page https://example.com/page 308
The docsite tool requires site data to be available in any of the following ways:
- A
docsite.jsonfile (or other file specified in the-configflag's search paths), as in the following example:{ "content": "../sourcegraph/doc", "baseURLPath": "/", "templates": "templates", "assets": "assets", "assetsBaseURLPath": "/assets/", "check": { "ignoreURLPattern": "(^https?://)|(^#)|(^mailto:support@sourcegraph\\.com$)|(^chrome://)" } } - In the
DOCSITE_CONFIGenv var, using Zip archive URLs fortemplates,assets, andcontent, as in the following example:DOCSITE_CONFIG='{"templates":"https://codeload.github.com/sourcegraph/sourcegraph/zip/refs/heads/main#*/doc/_resources/templates/","assets":"https://codeload.github.com/sourcegraph/sourcegraph/zip/refs/heads/main#*/doc/_resources/assets/","content":"https://codeload.github.com/sourcegraph/sourcegraph/zip/refs/heads/$VERSION#*/doc/","baseURLPath":"/","assetsBaseURLPath":"/assets/","defaultContentBranch":"main"}' docsite serve
-
Build the Docker image for
linux/amd64:docker build -t sourcegraph/docsite . # Use buildx if you're on M1 docker buildx build --platform linux/amd64 -t sourcegraph/docsite .
-
Tag and push the image to Docker Hub and GCR:
export VERSION= # e.g. v1.9.1 docker tag sourcegraph/docsite sourcegraph/docsite:$VERSION docker push sourcegraph/docsite docker push sourcegraph/docsite:$VERSION
-
For internal Sourcegraph usage:
- Bump the deployed version by updating the SHA-256 image digest in all files that define
sourcegraph/docsite:latest@sha256. - Once the pull request is merged, wait for the Buildkite build to pass.
- Bump the deployed version by updating the SHA-256 image digest in all files that define
-
For development, bump the version number in files that define
DOCSITE_VERSION.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent
