Structural changes to the DocCDocumentation Catalog

Sources/docc/DocCDocumentation.docc/DocC Documentation.md

@@ -10,7 +10,7 @@ Produce rich API reference documentation and interactive tutorials for your Swif
 
 The DocC documentation compiler converts Markdown-based text into rich documentation for Swift frameworks and packages. You can preview the documentation in its published form as you work on it, and also host it on a website when it's complete.
 
-DocC syntax — called _documentation markup_ — is a custom variant of Markdown that adds functionality for developer-specific documentation features, like cross-symbol linking, term-definition lists, code listings, and asides. You add documentation markup to your source code, compile it with DocC, and produce reference documentation for your APIs. You can also use documentation markup, along with a set of directives that instruct how DocC generates your content, to offer step-by-step tutorials that teach developers to use your APIs through interactive coding exercises.
+DocC syntax — called _documentation markup_ — is a custom variant of Markdown that adds functionality for developer-specific documentation features, like cross-symbol linking, term-definition lists, code listings, and asides. You add documentation markup to your source code, compile it with DocC, and produce reference documentation for your APIs. You can also use documentation markup, along with a set of directives that instruct how DocC generates your content, to offer step-by-step tutorials that teach developers to use your APIs through interactive coding exercises or to craft comprehensive articles that explain specific technologies or topics.
 
 ![On the left, a diagram shows a blocked-out example of a compiled tutorial and Markdown. In the middle, a diagram shows a blocked-out example of Markdown. On the right, a diagram shows a blocked-out example of compiled developer documentation.](docc-hero)
 
@@ -20,20 +20,29 @@ DocC syntax — called _documentation markup_ — is a custom variant of Markdow
 
 - <doc:documenting-a-swift-framework-or-package>
 
+### Documentation Content
+
 - <doc:writing-symbol-documentation-in-your-source-files>
 
+- <doc:adding-supplemental-content-to-a-documentation-catalog>
+
+- <doc:linking-to-symbols-and-other-content>
+
 ### Structure and Formatting
 
 - <doc:formatting-your-documentation-content>
 
+- <doc:other-formatting-options>
+
+- <doc:adding-images>
+
 - <doc:adding-structure-to-your-documentation-pages>
 
-- <doc:adding-supplemental-content-to-a-documentation-catalog>
+- <doc:customizing-the-appearance-of-your-documentation-pages>
 
 ### Distribution
 
 - <doc:distributing-documentation-to-other-developers>
-- <doc:customizing-the-appearance-of-your-documentation-pages>
 
 ### Documentation Types
 
@@ -45,4 +54,4 @@ DocC syntax — called _documentation markup_ — is a custom variant of Markdow
 
 - ``Comment``
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/api-reference-syntax.md

@@ -1,6 +1,6 @@
 # API Documentation
 
-Teach developers your Swift APIs through reference documentation you create from comments in source code and documentation extension files.
+Teach your APIs through reference documentation you create from code comments and extension files, or create detailed articles and conceptual guides.
 
 ## Overview
 
@@ -14,6 +14,7 @@ Use documentation markup, a custom variant of Markdown, to add in-source documen
 
 - ``Options``
 - ``Metadata``
+- ``TechnologyRoot``
 
 ### Creating Custom Page Layouts
 
@@ -22,4 +23,4 @@ Use documentation markup, a custom variant of Markdown, to add in-source documen
 - ``Links``
 - ``Small``
 
-<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->
+<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/docc/DocCDocumentation.docc/adding-images.md

@@ -0,0 +1,42 @@
+# Adding Images to Your Content
+
+Elevate your content's visual appeal by adding images.
+
+## Overview
+
+DocC extends Markdown's image support so you can provide appearance and 
+display scale-aware versions of an image. You use specific components to create image filenames, and DocC uses the most appropriate version of the image when displaying your documentation.
+
+![An image of a filename that's split into four labeled sections to highlight the individual components. From left to right, the components are the image name, the appearance mode, the display scale, and the file extension.](docc-image-filename)
+
+| Component | Description |
+| --- | --- |
+| Image name | **Required**. Identifies the image within the documentation catalog. The name must be unique across all images in the catalog, even if you store them in separate folders. |
+| Appearance | **Optional**. Identifies the appearance mode in which DocC uses the image. Add `~dark` directly after the image name to identify the image as a dark mode variant. |
+| Display scale | **Optional**. Identifies the display scale at which DocC uses the image. Possible values are `@1x`, `@2x`, and `@3x`. When specifying a display scale, add it directly before the file extension. |
+| File extension | **Required**. Identifies the type of image. The supported file extensions are `png`, `jpg`, `jpeg`, `svg` and `gif`. |
+
+> Tip: To best support your readers, provide images in standard resolution and `@2x` scale.
+
+For example, the following are all valid DocC image filenames:
+
+- term `sloth.png`: An image that's independent of all appearance modes and display scales.
+- term `sloth~dark.png`: An image that's specific to dark mode, but is display-scale independent.
+- term `sloth~dark@2x.png`: An image that's specific to dark mode and the 2x display scale.
+
+> Important: Include the image files in your documentation catalog. For more information, see <doc:documenting-a-swift-framework-or-package>.
+
+To add an image, use an exclamation mark (`!`), a set of brackets 
+(`[]`), and a set of parentheses (`()`).
+
+Within the brackets, add a description of the image. This text, otherwise known as _alternative text_, is used by screen readers for people who have vision difficulties. Provide enough detail to describe the image so that people can understand what the image shows.  
+
+Within the parentheses, include only the image name. Omit the appearance, 
+display scale, and file extension components. Don't include the path to the 
+image.
+
+```markdown
+![A sloth hanging off a tree.](sloth)
+```
+
+<!-- Copyright (c) 2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

Sources/docc/DocCDocumentation.docc/distributing-documentation-to-other-developers.md

@@ -39,10 +39,10 @@ docc convert MyNewPackage.docc \
   --output-dir MyNewPackage.doccarchive
 ```
 
-#### Include links to your project's sources
+#### Include Links to your Project's Sources
 
 When publishing documentation to an audience that has access to your project's
-sources, e.g., for an open-source project hosted on GitHub, consider configuring
+sources; for example, with an open source project hosted on GitHub, consider configuring
 DocC to automatically include links to the declarations of your project's symbols.
 
 For example, in the following screenshot, the "ParsableCommand.swift" link
@@ -113,7 +113,7 @@ documentation might resemble the following:
 https://www.example.com/documentation/MyNewPackage/MyNewProtocol
 ```
 
-#### Host a documentation archive with a file server
+#### Host a Documentation Archive with a File Server
 
 You can host documentation archives you create with DocC from the Swift 5.7 
 toolchain and later using a regular file server. By default, the server hosts 
@@ -145,7 +145,7 @@ the `DOCC_HOSTING_BASE_PATH` build setting when building documentation in Xcode.
 
 [plugin-docs]: https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-hosting-online/
 
-#### Host a documentation archive using custom routing
+#### Host a Documentation Archive Using Custom Routing
 
 A file server is the recommended solution to host your documentation. But, if 
 you need more control over how the server hosts your content, you can configure

Sources/docc/DocCDocumentation.docc/documenting-a-swift-framework-or-package.md

@@ -71,14 +71,16 @@ step-by-step, interactive content. For more information, see
 > Important: To use a documentation catalog in a Swift package, make sure the 
 manifest's Swift tools version is set to `5.5` or later. 
 
-## Building, publishing, and previewing documentation
+## Building, Publishing, and Previewing Documentation with the DocC Plug-in
 
 The preferred way of building documentation for your Swift package is by using
 the Swift-DocC Plugin. Refer to instructions in the plugin's 
 [documentation](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/)
 to get started with [building](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-a-specific-target), [previewing](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/previewing-documentation),
 and publishing your documentation to your [website](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-hosting-online) or [GitHub Pages](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/publishing-to-github-pages).
 
+You can also use the DocC command-line interface, as described in <doc:distributing-documentation-to-other-developers>.
+
 ## See Also
 
 - <doc:writing-symbol-documentation-in-your-source-files>