Highlighting documentation pages outside of Topics sections in Swift-DocC (@Links directive)

Development Swift-DocC
1

Hi all!

I'm excited to pitch the final piece (for now) of the authoring story for supporting more kinds of documentation in Swift-DocC. This pitch is a sibling of the following:

Problem

The introduction of @TopicsVisualStyle highlights a current deficiency in Swift-DocC's linking story. Links authored in a topics section like so:

## Topics

### Heading

- <doc:article>

receive a special visual treatment where they can be rendered with their abstract and, now, with their card image. However, writing links in a topics section also organizes the linked pages as children of the current page in the navigation sidebar. And there's no way to replicate this visual treatment outside of a topics section. So, if a writer wants to highlight a certain page in their documentation using the topics section visual style, they're now forced to also organize that page as a child which may lead to a sub-optimal navigation sidebar.

We should provide another way to author visual links to pages without the side affect of organizing those pages as children of the current page.

Solution

A new @Links directive that allows for authoring a Topics section anywhere on the page without affecting page curation behavior. @Links gives authors flexibility in choosing how they want to highlight documentation on the page itself versus in the navigation sidebar. It also allows for mixing and matching different visual styles of topics.

This would, for example, allow a developer to add a “What’s New” section to their top-level framework page:


# ``SlothCreator``

Catalog sloths you find in nature and create new adorable virtual sloths.

@Options {
   @TopicsVisualStyle(detailedGrid)
}

## Overview

SlothCreator provides models and utilities for creating, tracking, and caring for sloths.

You can visualize and observe your sloths by adding a ``SlothView`` to a SwiftUI view structure.

![A sloth hanging off a tree.](sloth.png)

### What's New in SlothCreator

@Links(visualStyle: compactGrid) {
   - <doc:get-started-preparing-sloth-food>
   - <doc:feeding-your-sloth-in-winter>
   - <doc:ordering-food-delivery>
}

## Topics

### Essentials

- <doc:/tutorials/SlothCreator>
- <doc:GettingStarted>
- ``Sloth``

### Creating a Sloth

- ``SlothGenerator``
- ``NameGenerator``

...

Links@2x
Links@2x1920×1229 120 KB


Thus, highlighting pages that are otherwise logically organized as children of other pages without needing to curate them twice and potentially confuse the experience of the navigation sidebar.

Details

@Links accepts a single visualStyle parameter and supports a list of Swift-DocC links as its child content:

  • visualStyle: The visual style of the topic links. Accepts one of the following:
    • list: Matches the current default Topics section style Swift-DocC uses. Includes the abstract for each page.
    • compactGrid: Matches the new compactGrid topics section visual style. A grid of items based on the card image for each page. Includes each page’s title and card image but excludes their abstracts.
    • detailedGrid: Matches the new detailedGrid topics section visual style option. A grid of items based on the card image for each page. Includes the abstract for each page.

@Links adds a lot of flexibility to on-page documentation organization. When combined with other directives like @Row/@Column the possibility for really unique documentation sites created with Swift-DocC is exciting. I'm looking forward to hearing your feedback on the naming and functionality of this new directive.

11 Likes
2

Almost missed this :slight_smile:
Looks great and I was looking for such a thing when linking other related packages or wwdc talks, looks great thank you!

2 Likes
3

This is definitely something I've missed so far! The only thing I'm not really happy about is the name; I think @Links doesn't really reflect the effect the directive actually has. The fact that its contents link to other pages is not due to the @Links directive, but due to the fact that the inner list only contains links.

I'd suggest a name like @NoCuration or @Uncurated. This naming scheme would also allow for a more structured usage of the directives in the future (if we want to support this):

![A sloth hanging off a tree.](sloth.png)

@Uncurated {
### What's New in SlothCreator

@TopicsVisualStyle(compactGrid) {
   - <doc:get-started-preparing-sloth-food>
   - <doc:feeding-your-sloth-in-winter>
   - <doc:ordering-food-delivery>
}

## Topics

### Essentials

- <doc:/tutorials/SlothCreator>
- <doc:GettingStarted>
- ``Sloth``

### Creating a Sloth
@Curated {
- ``SlothGenerator``
- ``NameGenerator``
}
...
}

Even if we're sure we never want to allow such nesting, I think a name such as @UncuratedLinks or @Links(curation: off, visualStyle: compactGrid) that is more explicit about the curation aspect wouldn't hurt.

4

I'm not fully happy with the name but I don't think tying this to curation behavior is the right thing either.

For newcomers to Swift-DocC, the directive needs to make sense on its own, separate from DocC's existing concept of curation in a # Topics section. What this directive allows for is the creation of high-resolution embedded links to other pages. I'm explaining it in the context of # Topics sections in the pitch since I think this audience is familiar with it, but I wouldn't reference DocC's curation behavior in the actual documentation for @Links.

The only place DocC supports curation is in Topics sections and I'm not proposing changing that with this pitch.

Additionally, a @Links directive can only contain links (not headings or other prose) so it's expected to be use in coordination with the other markup and block directives like @Row/@Column.

Separately, @TopicsVisualStyle is named the way it is because it affects topic sections, not @Link blocks. So I don't think accepting links as children of @TopicsVisualStyle fits into this model.

I agree with your sentiment of not being fully happy with the naming here and am definitely open to alternative naming suggestions for @Links, I just don't think referencing curation is the right direction here.

1 Like
5

This looks like a great addition to DocC, especially for landing pages, as you've demonstrated. Thanks, @ethankusters, can't wait!

2 Likes
6

Ah, I see...I think I misinterpreted the behavior quite a bit. So @Links has no real effect on curation behavior, i.e. it does not disable curation when used as part of a topics section, but instead it just allows creating (styled) link-lists outside of topic sections.

In that case I think the name @Links is fine!

1 Like
7

Thank you for the feedback here! Support for @Links in both Swift-DocC and Swift-DocC Render has landed in a nightly toolchain – please try it out if you're interested and provide feedback!

Relevant PRs:

1 Like