Docc might have some problems on Linux?

[kwmartin]

Landing page file being ignored in linux

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected behavior

The links under the ## Topics header should be shown in the landing page.

Actual behavior

After a 4.5 hour session, the best summary is just to paste what Perplexity finally, finally (yech!) stated:

You have set up everything as correctly as possible for DocC, but if you still do not see a link to Introduction or any content from TwosCmplt.md on the landing page, it is due to how DocC prioritizes and displays module landing pages for Swift packages with public symbols using static hosting. This is a widely reported limitation/bug and is not something you can fix via documentation content or curation alone.​

Why Your Topics Still Do Not Appear
When DocC generates documentation for a module with one or more public types, the package-level landing page becomes a listing of types (like “Structures,” “Classes,” etc.) and suppresses or ignores the narrative and topics from the root .md file.

This occurs even if the file and headings all match, and even if an explicit ## Topics section is at the top.

The “Topics” section and links from your TwosCmplt.md do not display because DocC’s static site generator does not surface curated topics or narrative on module landing pages for packages with symbols—only article pages (like Introduction.md) will display their content.

What You Can Do
This is not a bug in your markup or setup. There is no workaround to force DocC to show ## Topics or narrative from the module .md landing page in this hosting mode.

You should place all substantive documentation in a topic article such as Introduction.md.

Users must access Introduction by either direct link, sidebar navigation, or other DocC-generated navigation aids.

I haven't found this information in the documentation, and currently I don't know how to: access Introduction by either direct link, sidebar navigation, or other DocC-generated navigation aids.

Steps to Reproduce

I can supply where I'm at but it is big and making it into a small example is a big task. In the 4.5 hours, I went through every possible thing I could have done wrong. The summary, as seen from what Perplexity states, is the content and links of my TwosCmplt.md file in Sources/TwosCmplt/TwosCmplt.md are being ignored. The CLI command to generate the documentation done in TwosCmplt is:
swift package --allow-writing-to-directory ./docs generate-documentation --target TwosCmplt --output-path ./docs/TwosCmplt --transform-for-static-hosting --hosting-base-path TwosCmplt

I'm on Ubuntu 22.04 and every swift related thing is the most recent version. Perplexity states there is no workaroud. The whole point of docc is to supply hierarchical documentation so I'm at an impasse. All suggestions are very much appreciated.

[heckj]

Hi @kwmartin - can you be explicit about the URL in question here when you say "landing page"?

At first glance, this looks like it might be a duplicate of a known issue that requires /documentation/YourTargetName in the URL for a single target documentation bundle, which is agnostic to your build setup or hosting provider. (swiftlang/swift-docc#698)

But that said, I'm not sure where the markdown file is that you're wanting to be in the documentation, and how that aligns with anything else based on what you've provided so far. I'm afraid the perplexity description you included had more context about this problem than it shared, and I can't parse or infer what you're wanting and expecting, and what you have in place now, from it.

It may be that you haven't created a documentation catalog in your sources - which I'm guessing at based on your reference to Sources/TwosCmplt/TwosCmplt.md, which I suspect may be desired here.

The documentation at https://www.swift.org/documentation/docc/writing-symbol-documentation-in-your-source-files implies doing this with Xcode, but you can also create the directory and expected markdown file manually, here's some detail:

Adding a documentation catalog

The default documentation that DocC generates for a library includes all the public API symbols, organized by the type of symbol, then alphabetically.
A documentation catalog is a collection of markdown files and associated resources to extend and control the documentation output by DocC beyond what's available in your source files.
At a high level, it provides organization for the symbols, and lets you control the organization for all of the content, as well as additional media - such as images or videos - that you want to include with your documentation.
The documentation catalog can also host articles, tutorials, and longer form content about your symbols in your API that are awkward to include directly in the source.

A documentation catalog is a directory whose name ends with .docc with at least one markdown file inside.
A documentation catalog is typically tied to a target within a Swift package, and the package hosts the catalog within the source file directory for that target.

Adding a documentation catalog with Xcode:

If you're editing the package in Xcode, select the target's source directory and select File > New > File from Template...
and select Documentation Catalog from the templates.

Adding a documentation catalog without Xcode:

If you are working outside of Xcode, you can add the catalog by creating a directory and one or more markdown files.

• Add a directory, named Documentation.docc into your project alongside the target's sources.

For example, for a target named MyClient that uses the default location for its source files, the documentation catalog directory would be Sources/MyClient/Documentation.docc.

With the directory in place, the catalog needs at least one markdown file to provide the organization for the module.
A typical name for the top-level file is Documentation.md, and has a specific format that DocC looks for:

• A single, first-level header (#) with a symbol reference for the name of the module.
• A single line that provides the abstract for the module.
• An optional second-level header (##) with the name Overview
• A second-level header (##) with the name Topics.

The following content provides an example of the expected format:

# ``YourModuleName``

A single sentence summary of the module.

## Overview

A more extensive summary of the module, or general information introducing the module.
This can include multiple sentences, special formatting, lists, images, and so on.

## Topics

### First Topic Heading

- ``MyStruct``
- <doc:AnArticle>

Referencing symbols

A symbol reference in Markdown is the name of the symbol prefixed and suffixed with two backticks (``).
For more information on how to reference symbols, see Linking to Symbols and Other Content.

Organizing your documentation

The process of organizing the symbols, and any articles you create, in your DocC catalog is referred to as curation.
To curate your content, organize the symbols by action or function, generally grouping them into sets of 8 or fewer items under a topic heading.
As a general pattern, place the most commonly used or more important details at the top, with less important elements be
low.

The goal of curating is to provide the most relevant information first, using headings that let a developer skim through
the content to pinpoint the pieces they're interested in using as efficiently as possible.
As you curate your content, start with the most visible content — the top level document — and work your way down.

You can apply the same curation process within each of your symbols.
While you include this content within the code source files, it's often easier to include such organization outside of t
he source files.
The curation content can overwhelm the source files with content that's not directly relevant to the code, making it a d
istraction to developers working on the code.

To curate within a symbol, add an extension file, as described in Arrange Nested Symbols in Extension Files,
and provide the curation within that file.
For more information about the curation process, read Adding Structure to Your Documentation Pages.

Warning: Beneath the topics header (## Topics), DocC ignores content that it isn't looking for.

DocC expects the content to be marked as third-level (###) topic headers, with an optional sentence abstract beneath the topic header, and list items that reference symbols or document links.
DocC ignores arbitrary markdown, including external links, after the topics header.