{"id":13496765,"url":"https://github.com/ChimeHQ/Welp","last_synced_at":"2025-03-28T19:31:04.871Z","repository":{"id":103713907,"uuid":"554234821","full_name":"ChimeHQ/Welp","owner":"ChimeHQ","description":"Tooling for macOS help books","archived":false,"fork":false,"pushed_at":"2024-07-06T11:29:20.000Z","size":55,"stargazers_count":17,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-13T01:26:40.541Z","etag":null,"topics":["appkit","documentation","help","macos","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ChimeHQ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["mattmassicotte"]}},"created_at":"2022-10-19T13:25:53.000Z","updated_at":"2025-02-10T18:34:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"41cc509c-e9ee-4da0-a2b7-c12bf5169d9c","html_url":"https://github.com/ChimeHQ/Welp","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChimeHQ%2FWelp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChimeHQ%2FWelp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChimeHQ%2FWelp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ChimeHQ%2FWelp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ChimeHQ","download_url":"https://codeload.github.com/ChimeHQ/Welp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246088426,"owners_count":20721682,"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":["appkit","documentation","help","macos","swift"],"created_at":"2024-07-31T19:01:59.106Z","updated_at":"2025-03-28T19:31:04.522Z","avatar_url":"https://github.com/ChimeHQ.png","language":"Swift","funding_links":["https://github.com/sponsors/mattmassicotte"],"categories":["Swift"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n[![Build Status][build status badge]][build status]\n[![Matrix][matrix badge]][matrix]\n\n\u003c/div\u003e\n\n# Welp\nTooling for macOS help books.\n\nThe help book format for macOS is effectively abandoned. Yet, it still remains one of the best ways to deliver in-app help content. Nearly all of the built-in macOS apps use it. But, it can be a real struggle. Welp is all about building tooling to make the process easier.\n\nThe project has five components:\n\n- `Welp` library for working with help books programmatically\n- `welp` cli tool for help book automation\n- `Help Book.xctemplate` an Xcode template that sets up a help book bundle target\n- `WelpBook` a (very) experimental library that replaces the help book format entirely\n\nI have some [JavaScript](Help%20Book.xctemplate/helpbook.js) here that is needed to drive the in-browser navigation system. It does not work quite yet, and I also do not know the best way to distribute it. If you have ideas here, I'd love some help!\n\n## Installation\n\nWelp is available as both a command-line tool and a library.\n\nTool:\n\n```\nbrew tap ChimeHQ/Welp https://github.com/ChimeHQ/Welp.git\nbrew install welp\n```\n\nPackage:\n\n```swift\ndependencies: [\n    .package(url: \"https://github.com/ChimeHQ/Welp\", branch: \"main\")\n],\ntargets: [\n    .target(name: \"MyTarget\", dependencies: [\"Welp\"]),\n\t.target(name: \"MyOtherTarget\", dependencies: [\"WelpBook\"]),\n]\n```\n\n## Tool Usage\n\n*forthcoming - tool needs to be built first*\n\n## Template Usage\n\nFirst, the template must be installed. The on-disk path determines where Xcode displays it in its UI. These instructions place it in `macOS` \u003e `Other`, under the `Project Templates` main group.\n\n```bash\ncd Welp\nmkdir -p ~/Library/Developer/Xcode/Templates/Project\\ Templates/macOS/Other\ncp -r Help\\ Book.xctemplate ~/Library/Developer/Xcode/Templates/Project\\ Templates/macOS/Other/\n```\n\nUnfortunately, this template is missing a few features. This means there are some extra steps required to make it actually work.\n\n#### Copy\n\nAdd the help book bundle into your main app via the \"Copy Bundle Resources\" phase.\n\nI *thought* that `AssociatedTargetNeedsProductBuildPhaseInjection` would make this automatic, but I cannot figure out how to control how Xcode adds it into the associated target's build phases.\n\n#### Info.plist Addition\n\nI *think* it is necessary to add an entry into your main app's Info.plist. `CFBundleHelpBookFolder` should be set to `YourHelpBook.help`.\n\n## WelpBook Usage\n\nPlease do keep in mind this is experimental. This provides an interface to the `NSUserInterfaceItemSearching` API.\n\n```swift\nHelp.register(Help.Handlers(items: searchItems, allTopics: allTopics))\n\nfunc searchItems(_ query: String, limit: Int) async -\u003e [Help.Item] {\n    // perform your query and produce at most `limit` items\n    \n    return items\n}\n\n@MainActor\nfunc allTopics(_ query: String) {\n    // Handle the \"Show All Help Topics\" items for a given query string \n}\n```\n\n## References\n\n- [Authoring Apple Help](https://developer.apple.com/library/archive/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/authoring_help/authoring_help_book.html)\n- [Authoring macOS Help Books in 2020 (and beyond)](https://marioaguzman.wordpress.com/2020/09/12/auth/)\n- [Why won't that help book open](https://eclecticlight.co/2021/11/16/why-wont-that-help-book-open/)\n- [Phel: Publish help books for your Mac apps](https://www.checksimsoftware.com/phel/)\n\n## Contributing and Collaboration\n\nI'd love to hear from you! Get in touch via an issue or pull request.\n\nI prefer collaboration, and would love to find ways to work together if you have a similar project.\n\nI prefer indentation with tabs for improved accessibility. But, I'd rather you use the system you want and make a PR than hesitate because of whitespace.\n\nBy participating in this project you agree to abide by the [Contributor Code of Conduct](CODE_OF_CONDUCT.md).\n\n[build status]: https://github.com/ChimeHQ/Welp/actions\n[build status badge]: https://github.com/ChimeHQ/Welp/workflows/CI/badge.svg\n[matrix]: https://matrix.to/#/%23chimehq%3Amatrix.org\n[matrix badge]: https://img.shields.io/matrix/chimehq%3Amatrix.org?label=Matrix\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChimeHQ%2FWelp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FChimeHQ%2FWelp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FChimeHQ%2FWelp/lists"}