Hello! I’m here to propose a couple new features for Swift-DocC to enable a new kind of capability. Often, when writing documentation, it’s useful to point to a sample project that demonstrates some functionality in your package. For example, Swift Argument Parser includes example scripts in their repository do demonstrate its use. However, there’s currently no way to signal that a page is specifically there to demonstrate the sample project instead of some other concept. I’d like to add that ability to Swift-DocC.
@CallToAction: Adding a top-level link to a page’s header
The @CallToAction directive adds a prominent link to the header of a page, indicating a downloadable asset, or an important link for that page. It would go in the page metadata, like this:
@Metadata {
@CallToAction(url: "https://github.com/apple/swift-argument-parser/blob/main/Examples/math/Math.swift", label: "View on GitHub")
}
The directive adds a button to the page header linking to the given url. In this case, the button says “View on GitHub” and links to Swift Argument Parser’s “Math” example on GitHub.
@CallToAction can also be used to link directly to a file to download, by providing the appropriate URL:
@Metadata {
@CallToAction(url: "https://example.com/sample.zip", label: "Download")
}
This example would look like this on the rendered page:
An alternate version is available to link to a file local in your documentation bundle:
@Metadata {
@CallToAction(file: "sample.zip", label: "Download")
}
This creates a URL relative to the documentation bundle (e.g. MyPackage.docc/sample.zip), and allows you to reference a file without requiring you to upload it separately.
@CallToAction also has a mechanism to supply a default label, using the purpose argument:
@Metadata {
@CallToAction(url: "https://example.com/sample.zip", purpose: download)
}
The purpose argument specifies the default label applied to the button. The allowed kinds are download (labeled “Download”) and link (labeled “Visit”).
Only one @CallToAction directive is allowed on a page. One of url or file is required, as is one of purpose or label.
@PageKind: Overriding a page’s kind metadata in the navigator
The @PageKind directive dictates how a page is displayed in the navigator and in its header. Swift-DocC supports displaying a handful of page kinds other than the standard Symbol, Article and Tutorial, and this directive allows documentation authors to more accurately portray what a page is.
This directive is written in the page metadata, like this:
@Metadata {
@PageKind(sampleCode)
}
The allowed values include the following:
-
article(default for.mdarticle files) sampleCode
The selected page kind also sets the “role heading” for the page (colloquially known as the “eyebrow text”). By default, the headings are “Article” and “Sample Code” respectively. To set a custom role heading, the proposed @TitleHeading directive can be used.
Combining this with the above example, the header now looks like this:
It also sets the icon in the sidebar navigator:
Future directions
The @PageKind directive can be extended fairly straightforwardly in the future. There are several page roles that Swift-DocC can support, but many of these are currently unused.
Outside of these directives, i’m excited to see where we can build from here. It’s possible to use these hooks to build, for example, tooling that would wrap Swift-DocC to create Sample Code articles for items in an Examples/ directory, or the like.