From 0714297fe74f60c9b1601de733ae0b7aaa10343b Mon Sep 17 00:00:00 2001 From: Yann Bertrand <5855339+yannbertrand@users.noreply.github.com> Date: Thu, 19 Dec 2024 22:50:26 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20a=20contribution=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/.vitepress/config.js | 1 + docs/contributing.md | 328 ++++++++++++++++++++++++++++++++++++++ docs/index.md | 4 +- readme.md | 24 +-- 4 files changed, 335 insertions(+), 22 deletions(-) create mode 100644 docs/contributing.md diff --git a/docs/.vitepress/config.js b/docs/.vitepress/config.js index 93dd622a..11515ebf 100644 --- a/docs/.vitepress/config.js +++ b/docs/.vitepress/config.js @@ -285,6 +285,7 @@ export default defineConfig({ 'lsquarantine.md', 'nsclosealwaysconfirmschanges.md', ], + excludePattern: ['contributing.md'], }), editLink: { pattern: diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..d8f988bb --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,328 @@ +--- +title: macOS defaults contribution guide +description: To contribute to the website, follow these guidelines. +head: + - - meta + - property: 'og:title' + content: macOS defaults > contributing + - - meta + - property: 'og:description' + content: To contribute to the website, follow these guidelines. +outline: [2, 3, 4] +--- + +# Contributing + +In case your interested in contributing to the macOS defaults website, please respect the following rules. + +All the listed `defaults` commands are Markdown files stored in the [docs folder](https://github.com/yannbertrand/macos-defaults/tree/main/docs). It is recommended to look at a few of them before proposing a new one: + +- https://macos-defaults.com/dock/orientation.html +- https://macos-defaults.com/dock/autohide-time-modifier.html +- https://macos-defaults.com/screenshots/disable-shadow.html + +## Creating the page + +- Each page references one command. +- The page should be a `.md` file in one folder inside `docs`. +- Do not create a new folder for one page only. At least 3 pages are needed before considering creating a folder. Use the `misc` folder in case you can't find one. +- The filename should be the lowercased command key. Examples: + - `defaults write com.apple.dock "autohide" -bool "true"` is `autohide.md` + - `defaults write NSGlobalDomain "AppleSpacesSwitchOnActivate" -bool "true"` is `applespacesswitchonactivate.md` + - `defaults write com.apple.dock "scroll-to-open" -bool "true"` is `scroll-to-open.md` + +## Page content + +> [!IMPORTANT] +> All infos must be unopionated. +> +> Avoid words like "enable"/"disable", "allow"/"disallow", "turn on"/"turn off"... +> Prefer "toggle", "switch", "set"... + +### Meta informations + +Some meta informations are required to ensure proper SEO and social media sharing. VitePress uses [Frontmatter](https://vitepress.dev/guide/frontmatter) to fill in these info. + +::: details Complete example: + +```md +--- +title: Autohide animation time | Dock +description: Change the Dock opening and closing animation times. +head: + - - meta + - property: 'og:title' + content: macOS defaults > Dock > Autohide animation time + - - meta + - property: 'og:description' + content: Change the Dock opening and closing animation times. +--- +``` + +::: + +The following fields are mandatory. + +#### Title + +> [!IMPORTANT] +> The page title must be 1 to 5 words. + +| Field name | Format | Usage | +| ---------- | --------------------------------------- | ------------ | +| `title` | `${title} \| ${folder}` | SEO | +| `og:title` | `macOS defaults > ${folder} > ${title}` | Social Media | + +#### Description + +> [!IMPORTANT] +> The page description should be 1 sentence. + +| Field name | Format | Usage | +| ---------------- | ----------------- | ------------ | +| `description` | Ending with a dot | SEO | +| `og:description` | Ending with a dot | Social Media | + +### Heading section + +#### Page title + +> [!IMPORTANT] +> Title must be 1 to 5 words. + +It's used to generate the sidebars and the Table of contents. + +##### Example: + +```md +# Page title +``` + +#### Description + +Example: + +```md +Describe what the command is doing. + +Please add some context if it is helpful. + +Specify if the command cannot be activated directly: + +> ⚠️ A restart of your Mac is required to apply these changes. +``` + +Take a look at the [mouse acceleration command](/mouse/linear.md#acceleration) for a well written complete description. + +#### Version support + +Only include the versions you tested. Sort the versions in reverse release date order. + +##### Example: + +```md +**Tested on macOS:** + +- Sequoia +- Sonoma +``` + +#### Command parameter + +`defaults` commands can take various parameter types: + +- `bool` +- `int` +- `float` +- `string` +- `array` + +It is possible to find the type of a command with the `defaults` CLI using: + +```bash +defaults read-type ${domain} ${key} +``` + +When the possible values are limited, please list them. + +##### Example: + +```md +**Parameter type**: int +**Accepted parameter values**: + +- 0 +- 2 +- 3 +``` + +#### Command requirements + +Some commands have prerequisites. List them in this section. + +##### Example: + +```md +## Requirements + +- [`com.apple.dock autohide`](/dock/autohide.md#set-to-true) must be set to `true` +``` + +### Command demos + +At least 4 sections are needed: + +- Set the domain's key to some value +- Set the domain's key to the default value +- Read current domain's key value +- Reset the domain's key value + +Each of them contain a bash command the user can copy. It should use double quotes around the key for stability. + +The command should be self-sufficient, usually there is a `killall ${app_name}` command that is needed. + +The first two sections contain a description of what the command does. +Avoid direct parameter values such as `0` as type could be wrongly interpreted, always prefer `-${type} "${value}"` with quoted value. +These can and should when possible include a screenshot or a video to demo what the command does. + +::: details Example with images demos: + +````md +## Set to `36` + +Dock icon size of 36 pixels. + +```bash +defaults write com.apple.dock "tilesize" -int "36" && killall Dock +``` + +Example output with value set to 36 + +## Set to `48` (default value) + +Dock icon size of 48 pixels. + +```bash +defaults write com.apple.dock "tilesize" -int "48" && killall Dock +``` + +Example output with value set to 48 + +## Read current value + +```bash +defaults read com.apple.dock "tilesize" +``` + +## Reset to default value + +```bash +defaults delete com.apple.dock "tilesize" && killall Dock +``` +```` + +::: + +Take a look at the [Dock's autohide delay command for video examples](https://github.com/yannbertrand/macos-defaults/edit/main/docs/dock/autohide-delay.md). + +### macOS UI Alternative + +Majority of commands can be updated from macOS UI. When possible, please include the way to do it. + +Some macOS System Settings can be directly accessed via special links. E.g. Access Dock settings. You can find this URL with the Script Editor App using this script: + +```applescript +tell application "System Settings" + set myIds to the id of every pane + set myAnchors to anchors of current pane +end tell +``` + +##### Example: + +```md +## Set value from UI + +1. Access Dock settings from macOS UI +2. Set "Position on the screen" dropdown value +``` + +### Complete page example + +Here is a complete template you can copy: + +````md +--- +title: Icon size | Dock +description: Set the icon size of Dock items in pixels. +head: + - - meta + - property: 'og:title' + content: macOS defaults > Dock > Icon size + - - meta + - property: 'og:description' + content: Set the icon size of Dock items in pixels. +--- + +# Icon size + +Set the icon size of Dock items in pixels. + +- **Tested on macOS**: + - Sequoia + - Sonoma +- **Parameter type**: int + +## Set to `36` + +Dock icon size of 36 pixels. + +```bash +defaults write com.apple.dock "tilesize" -int "36" && killall Dock +``` + +Example output with value set to 36 + +## Set to `48` (default value) + +Dock icon size of 48 pixels. + +```bash +defaults write com.apple.dock "tilesize" -int "48" && killall Dock +``` + +Example output with value set to 48 + +## Read current value + +```bash +defaults read com.apple.dock "tilesize" +``` + +## Reset to default value + +```bash +defaults delete com.apple.dock "tilesize" && killall Dock +``` + +## Set value from UI + +1. Access Dock settings from macOS UI +2. Slide "Size" range value +```` diff --git a/docs/index.md b/docs/index.md index cb9339e1..0124e8d5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -88,7 +88,9 @@ defaults rename ${domain} ${old_key} ${new_key} ## 🤔 How do I add a command? -Please take [a look at the GitHub project](https://github.com/yannbertrand/macos-defaults#add-a-command). Feel free to open an issue if you know an unlisted command. It's also possible to add the command yourself by creating a Pull Request. +Feel free to open a [GitHub issue](https://github.com/yannbertrand/macos-defaults/issues) if you know an unlisted command. + +It's also possible to add the command yourself by creating a Pull Request. Please take [a look at the contribution guidelines](/contributing.md). ## ❤️ I like this website, how can I build the same? diff --git a/readme.md b/readme.md index a3834785..728b494e 100644 --- a/readme.md +++ b/readme.md @@ -16,27 +16,9 @@ An up-to-date list of [macOS `defaults` commands](https://macos-defaults.com) wi ## Add a command -All the listed `defaults` commands are Markdown files stored in the [docs folder](./docs). It is recommended to look at a few of them before proposing a new one: - -- https://macos-defaults.com/dock/orientation.html -- https://macos-defaults.com/dock/autohide-time-modifier.html -- https://macos-defaults.com/screenshots/disable-shadow.html - -Here are the mandatory infos to add a new command: - -- The defaults command's domain -- The command's key -- A neutral title -- A simple description -- Parameter type, and list of accepted values when applicable -- Other command dependency -- A scenario to test the command is still working -- The corresponding option access from UI when it exists -- At least two examples with a small text description -- Ideally, an image or video for each example -- Compatible versions it has been tested on - -I will always prefer images and videos examples as they help users and maintenance a lot! Please consider it if you want to [open a PR](https://github.com/yannbertrand/macos-defaults/compare). +Feel free to open an issue if you know an unlisted command. + +It's also possible to add the command yourself by creating a Pull Request. Please take [a look at the contribution guidelines](https://macos-defaults.com/contributing.html). ### How to discover a `defaults` command