‘you must add the /tutorials/ prefix to the path’: really?

according to the official DocC documentation, you must link to DocC tutorials using the absolute /tutorials/ syntax:

Links to tutorials follow the same format, except you must add the /tutorials/ prefix to the path:

<doc:/tutorials/SlothCreator>

but it doesn’t really seem like this is actually required, as i have noticed swift-openapi-generator is just linking to its tutorials using bare tutorial name references:

## Topics

### Essentials
- <doc:Checking-out-an-example-project>
- <doc:ClientSwiftPM>
- <doc:ClientXcode>
- <doc:ServerSwiftPM>

do these docs need to be updated?

Yes, the "tutorials" prefix is not necessary in the link. I don't think it ever was.

1 Like

I opened a PR to update the documentation about this.

i am a little confused by the passage about using /documentation/ArticleName - my understanding was that the format goes /documentation/ModuleName/ArticleName and tutorials just replaces the module name in the path prefix. did this change?

You could say that links to articles and tutorials has 3 path components, where the first two are optional

  • Either documentation or tutorials
  • The documentation "display name"
  • The name of the article or tutorial file without file extensions

If the documentation contains symbol information and doesn't explicitly specify a display name, the display name will be inferred from the module name but it is possible for them to differ. This distinction only matters for symbols (see last paragraph).

So, it's possible to link to an article or tutorial using any of the following components (the extra whitespace wouldn't be present in the link):

< doc :                               ArticleName >
< doc :                 DisplayName / ArticleName >
< doc : documentation /               ArticleName >
< doc : documentation / DisplayName / ArticleName >
 
< doc :                               TutorialName >
< doc :                 DisplayName / TutorialName >
< doc : tutorials     /               TutorialName >
< doc : tutorials     / DisplayName / TutorialName >

This is the syntax from the original open source version that new versions of DocC has remained compatible with.

Links to symbols can use a "documentation" prefix but then the rest of the link needs to be absolute, starting with the module name. Links to symbols use the module name in the link even if the documentation has an explicit display name that is different from the module name.

thank you for the explanation, i had never heard of a path syntax that allows omission of interior path components. what was the motivation for this? and how does the link resolver know when/where to insert implicit path components?

what happens if i have a module named documentation? (not an esoteric use case, i frequently have empty modules named guides that just contain markdown articles.)

The motivation is solely to remain backwards compatible with earlier syntax versions.

Note; if the documentation only contains markdown articles then it would be a documentation "display name" and not a "module name".

It doesn't cause any issued because both these interpretations of the link find the same article

< doc :                 documentation / ArticleName >
< doc : documentation /                 ArticleName >

Still, the recommended link would be simply <doc:ArticleName>

If the documentation contains tutorials but has a display name that's "documentation" then the link may look a bit odd if you opt to include the display name in the link but the recommended link would be simply <doc:TutorialName> which doesn't have this problem.

The old behavior—that DocC remains backwards compatible with—is to prefer article matches over tutorial matches, so if you had documentation with a display name that's "documentation" and an article and tutorial file with the same base name, then <doc:FileName> would unambiguously resolve to the article. Again, because the article match is preferred over the tutorial match—for backwards compatibility—the link <doc:documentation/FileName> would also unambiguously resolve to the article instead of the tutorial. In this very specific case you'd need to use either <doc:tutorials/FileName> or <doc:tutorials/documentation/FileName> to refer to the tutorial. Regardless of what the display name is, including it in the link doesn't change what the link resolves to when an article file and tutorial file has the same base because the article match is prioritized and the article and tutorial have the same display name component.

Maybe one day we'll phase out these old behaviors but we'd need to add new warnings to let people know that they need to make changes to links in their content.