{"id":18739711,"url":"https://github.com/roblabs/swift-docc-template","last_synced_at":"2025-11-19T14:30:18.619Z","repository":{"id":201051576,"uuid":"704310719","full_name":"roblabs/swift-docc-template","owner":"roblabs","description":"Use DocC to build and share documentation for non-swift projects.","archived":false,"fork":false,"pushed_at":"2023-10-31T19:03:37.000Z","size":566,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"trunk","last_synced_at":"2025-02-14T06:14:59.196Z","etag":null,"topics":["docc","documentation","documentation-tool","swift","swift-documentation"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roblabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-10-13T01:54:12.000Z","updated_at":"2023-10-25T00:18:04.000Z","dependencies_parsed_at":"2023-10-22T19:45:09.103Z","dependency_job_id":"9b2417f0-63cb-453f-bf47-b828f5ee0562","html_url":"https://github.com/roblabs/swift-docc-template","commit_stats":null,"previous_names":["roblabs/swift-docc-template"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roblabs%2Fswift-docc-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roblabs%2Fswift-docc-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roblabs%2Fswift-docc-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roblabs%2Fswift-docc-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roblabs","download_url":"https://codeload.github.com/roblabs/swift-docc-template/tar.gz/refs/heads/trunk","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239619570,"owners_count":19669447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docc","documentation","documentation-tool","swift","swift-documentation"],"created_at":"2024-11-07T15:37:06.570Z","updated_at":"2025-11-19T14:30:18.573Z","avatar_url":"https://github.com/roblabs.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Swift-DocC Template\n\nUse Swift-DocC to build and share documentation for most any software code project.  You can build documentation as a Swift-DocC article or sample code, even if it is not Swift code.  \n\n## Overview\n\nUse this starter template to create rich documentation and interactive tutorials for *non* Swift projects.  For example, you can write an article on the development of creating web maps that is heavy with GeoJSON, JSON, or TypeScript.  See the section [Add Code Listings][Add Code Listings] for the programming languages where you can enable syntax highlighting.\n\nYou can edit with Xcode 15 and its Documentation Preview assistant editor, which gives you a view of your documentation as you type, allowing you to iterate on your documentation without leaving the Xcode.  Or, you can use your favorite editor and generate documentation from a [Swift based command line][Swift based command line].  The generated Swift-DocC documentation can be published to a static web host.\n\nThe template makes use of the [Swift Package Manager command plugin for Swift-DocC][Swift Package Manager command plugin for Swift-DocC], which has the [Swift-DocC documentation site][Swift-DocC documentation site].\n\n[Swift based command line]: https://www.swift.org/install \"Swift development is officially supported on Apple platforms, Linux, and Windows.\"\n[Add Code Listings]: https://www.swift.org/documentation/docc/formatting-your-documentation-content#Add-Code-Listings \"code listings, or fenced code blocks\"\n[Swift Package Manager command plugin for Swift-DocC]: https://github.com/apple/swift-docc-plugin \"The Swift-DocC plugin is a Swift Package Manager command plugin that supports building documentation for SwiftPM libraries and executables.\"\n[Swift-DocC documentation site]: https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin \"Swift-DocC documentation for the plugin.\"\n[pre-built Swift-DocC web renderer]: https://github.com/apple/swift-docc-render-artifact \"Pre-built copy of the web renderer for Swift-DocC documentation.\"\n\n### Test\n\nRun \u0026 build using the DocC command of your choice (either from Xcode or a Swift Docker Container).  The name of the root documentation is called `docctemplate` at the top level header.  \n\n* \u003chttp://server:4256/documentation/docctemplate\u003e\n\nThis name matches in both `Documentation.docc/Documentation.md` and the minimal symbols JSON file `Documentation.docc/DocC.symbols.json`.  When you want to change the name, be sure to change `docctemplate` in both files.\n\n`Documentation.md` in the top level header, found on line 1.\n\n```markdown\n# ``docctemplate``\n```\n\n`DocC.symbols.json` in the `module` key.\n\n```json\n  \"module\": {\n    \"name\": \"docctemplate\",\n    ...\n  }\n```\n\n## Topics\n\n* [Meet DocC documentation in Xcode](https://developer.apple.com/videos/play/wwdc2021/10166 \"site: developer.apple.com\")\n  * [Xcode 15's Documentation Preview assistant editor](https://developer.apple.com/videos/play/wwdc2023/10244/?time=485 \"Video demo of Documentation Preview at developer.apple.com\")\n  * [Search Swift-DocC Videos at developer.apple.com](https://developer.apple.com/search/?q=docc\u0026type=Videos \"Search Swift-DocC Videos at Apple\")\n    * [Create rich documentation with Swift-DocC](https://developer.apple.com/wwdc23/10244 \"Swift-Doc video at developer.apple.com\")\n* [Produce rich API reference documentation and interactive tutorials site](https://www.swift.org/documentation/docc \"swift.org version of Swift-DocC\")\n* For examples of Swift-DocC tutorials, see \u003chttps://developer.apple.com/tutorials\u003e\n  * [Introducing SwiftUI](https://developer.apple.com/tutorials/SwiftUI \"SwiftUI Tutorials at developer.apple.com\")\n  * [Bring an iPad App to the Mac with Mac Catalyst](https://developer.apple.com/tutorials/Mac-Catalyst \"Mac Catalyst Tutorials at developer.apple.com\")\n\n---\n\n## Command Line\n\n### Xcode\n\nOpen via the Xcode text editor invocation tool.\n\n```console\nxed Package.swift\n```\n\nPreview documentation from a source bundle.\n\n```console\n# xcrun docc preview -h\n#    Port number to use for the preview web server.\nxcrun docc preview Documentation.docc --port 4256 --output-path tmp/dist\n```\n\n### DocC with Docker\n\nSwift-DocC is integrated with the Swift toolchain since Swift 5.6.\n\nWith Docker, consider using `docc convert` instead of `docc preview`, and then plan on using your own web server.\n\nTo install Swift Docker see:  \u003chttps://www.swift.org/install/linux/#installation-via-docker\u003e\n\n```console\n# docker pull swift\ndocker run --rm --privileged --interactive --tty \\\n  --volume $(pwd):/home                          \\\n  --workdir /home                                \\\n  --name swift-latest swift:latest /bin/bash\n```\n\n```console\n# make a temporary directory output\nmkdir -p tmp\n```\n\n### Staging\n\nConvert documentation from a source bundle\n\n* Set a test output folder\n* serve that folder for testing\n* Do not commit to GH Pages, as the `baseUrl` is set for local testing.\n\n```console\n# docc -h\n# docc convert -h\ndocc convert Documentation.docc --output-path tmp/distFromDocker\n```\n\n### Production\n\nConvert documentation from a source bundle, and prepare for hosting on GH Pages\n\nSince we used the switch `--hosting-base-path docs`, then this is the version that would be posted to GitHub Pages and assumes that the root is `/docs`.\n\n* Set the producttion output folder\n* you will not be able to serve that folder for testing\n* This can be committed to GH Pages, as the `baseUrl` is set for production\n\n\n```console\ndocc convert Documentation.docc --output-path docs --hosting-base-path \u003cnameOfYourGHRepoName\u003e\n```\n\n### GitHub Settings for DocC\n\n* Output the generated HTML to `\u003crepo_root\u003e/docs` on the local drive\n* Set the branch to `docs` and serve from GH Pages the folder within the branch called `/docs`\n* See the `docc` help for `--hosting-base-path`\n  * `docc convert -h`\n\n![](assets/GHPages.png)\n\n### Swift Command Line\n\nFor example, you can use these command directly in macOS or from your Docker container.\n\nResolve package dependencies.\n\n```console\n# Optionally `clean`\n# rm -rf .build .swiftpm Documentation.docc/.docc-build\n\n# swift package resolve -h\nswift package resolve\n```\n\nArtifact management via `swift package clean | reset`.\n\n```console\n# Online help\nswift package\n\n# SUBCOMMANDS:\n#  clean                   Delete build artifacts\n#  reset                   Reset the complete cache/build directory\n```\n\nDisplay available options.\n\n```console\nswift -help\n```\n\n### Swift Versions  \n\nPrint Swift version information and exit.\n\n```console\nswift -version\n```\n\n#### macOS Big Sur (11.7.10) 🔴\n\nSwift 5.6 is required in order to run the [Swift Package Manager command plugin for Swift-DocC][Swift Package Manager command plugin for Swift-DocC].  Use Docker if you need DocC on macOS Big Sur.\n\n    swift-driver version: 1.26.21 Apple Swift version 5.5.2 (swiftlang-1300.0.47.5 clang-1300.0.29.30)\n    Target: x86_64-apple-macosx11.0\n\n#### macOS Sonoma (14)\n\n    swift-driver version: 1.87.1 Apple Swift version 5.9 (swiftlang-5.9.0.128.108 clang-1500.0.40.1)\n    Target: x86_64-apple-macosx14.0\n\n#### Docker `swift:latest`\n\n    Swift version 5.9 (swift-5.9-RELEASE)\n    Target: x86_64-unknown-linux-gnu\n\n---\n\n*Customization example with `@Metadata` directives.*\n![Example of some of the @Metadata directives.](Documentation.docc/Resources/Documentation@2x.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froblabs%2Fswift-docc-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froblabs%2Fswift-docc-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froblabs%2Fswift-docc-template/lists"}