You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Guides/docs.docc/Getting started.md
+2-2Lines changed: 2 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
# Getting started with Unidoc
1
+
# Bootstrapping Unidoc
2
2
3
3
This guide outlines how to set up and run a local Unidoc server you can use to preview your documentation as it would appear on [Swiftinit](https://swiftinit.org).
4
4
@@ -16,7 +16,7 @@ It is theoretically possible to run Unidoc without Docker, but Docker makes it m
16
16
The examples in this tutorial assume you are building Unidoc from source. However, you can also download [pre-built binaries](/Quickstart) for a select set of platforms.
17
17
18
18
19
-
## Setting up a local database automatically
19
+
## Setting up a local database automatically
20
20
21
21
Unidoc can set up a `mongod` instance for you automatically through the `unidoc init` command. This tool takes a directory path as an argument, which it uses to persist the state of the database. In the example below, we will create the documentation database in a directory named `unidoc` in your home directory.
Copy file name to clipboardExpand all lines: Guides/docs.docc/Quickstart.md
+10-9Lines changed: 10 additions & 9 deletions
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Previewing documentation locally
2
2
3
-
This guide walks through how to use the `unidoc preview` tool to preview documentation locally on macOS 15. This guide won’t make any effort to explain how Unidoc itself works, it is merely intended to demonstrate how to preview multi-package documentation as quickly as possible. For a more-detailed Linux-centric tour, see the <doc:Getting-started> guide.
3
+
This guide walks through how to use the `unidoc preview` tool to preview documentation locally on macOS 15. This guide won’t make any effort to explain how Unidoc itself works, it is merely intended to demonstrate how to preview multi-package documentation as quickly as possible.
4
4
5
5
In this guide, you will:
6
6
@@ -13,7 +13,7 @@ In this guide, you will:
13
13
14
14
## 1. Install Docker
15
15
16
-
The easiest way by far to preview documentation locally is to use Docker. You can download Docker Desktop for macOS from the [official website](https://www.docker.com/products/docker-desktop).
16
+
The easiest way to preview documentation locally is to use Docker. You can download Docker Desktop for macOS from the [official website](https://www.docker.com/products/docker-desktop).
17
17
18
18
19
19
## 2. Install Unidoc
@@ -24,13 +24,14 @@ Today, there are two main ways to install Unidoc — building it from source or
24
24
25
25
Pre-built binaries are available for a limited set of platforms.
Follow our [quickstart guide](https://swiftinit.org/docs/swift-unidoc/guides/quickstart) to learn how to set up a local Unidoc server.
37
+
26
38
27
39
## Features
28
40
41
+
### ✏️ Powerful symbol links
42
+
43
+
Unidoc supports the [UCF](https://github.com/tayloraswift/swift-ucf) symbol link syntax — a superset of the DocC symbol link syntax — which supports [multi-component paths, cross-module references, and type signature disambiguation](https://swiftinit.org/docs/swift-ucf/help/codelinks).
The Unidoc documentation compiler can be run in CI mode to validate documentation and fail the pipeline if documentation errors (such as broken links) are diagnosed.
54
+
55
+
The Unidoc compiler can diagnose *all* broken symbol links, including references to symbols in package dependencies and the standard library.
56
+
57
+
We provide the [swift-unidoc-action](https://github.com/tayloraswift/swift-unidoc-action) for GitHub Actions.
58
+
59
+
```yaml
60
+
- name: Validate documentation
61
+
run: |
62
+
unidoc compile \
63
+
--swift-toolchain $SWIFT_INSTALLATION \
64
+
--ci fail-on-errors \
65
+
--project-path .
66
+
```
67
+
68
+
### ✂ Rich code snippets
69
+
70
+
Unidoc can render SwiftPM code snippets in documentation with linked IDE-style code references and hover-over tooltips.
71
+
72
+
See [swiftonserver.com](https://swiftonserver.com/realtime-mongodb-updates-with-changestreams-and-websockets/#The%20Connection%20Manager), which uses Unidoc as its rendering backend, for an example of code snippets in action.
73
+
29
74
### 🪶 Small archive sizes
30
75
31
76
Unidoc servers are designed to store versioned documentation indefinitely. To achieve this, Unidoc uses a stable binary symbol graph format that can be up to two orders of magnitude smaller than an equivalent DocC archive.
0 commit comments