[
{
"path": ".github/CONTRIBUTING.md",
"content": "# Contributing to macOS Setup Guide\n\nContributions to macOS Setup Guide are more than welcome.\n\n## License\n\nBy contributing code to macOS Setup Guide, you agree to license your\ncontribution under the [MIT License](../LICENSE).\n\n## Installing dependencies and linting\n\nRun `make deps` first to make sure all the dependencies are installed in the workspace. Then run `make lint` before submitting your PR to make sure your changes comply\nwith our styling.\n\n## How to contribute to macOS Setup Guide\n\nIf you would like to submit a pull request, please base it on our\n[template](CONTRIBUTION_TEMPLATE.md). Not only does this make things easier for\n_you_ to know what to include in your contribution, it makes the guide more\nconsistent which results in a better experience for the user. Thank you.\n"
},
{
"path": ".github/CONTRIBUTION_TEMPLATE.md",
"content": "\n\n# Tool/library/language name\n\n\n## Installation\n\n\n## Usage\n\n\n## Customization\n\n\n## More\n\n\n"
},
{
"path": ".github/ISSUE_TEMPLATE.md",
"content": "\n\n### I'm Submitting a ...\n\n```\n[ ] Bug report\n[ ] Tool/language/etc documentation request\n```\n\n### Bug Location\n\n\n### Tool/Language/etc\n\n\n### Other Information\n\n"
},
{
"path": ".github/workflows/links.yml",
"content": "name: Validate URLs\n\non:\n schedule:\n - cron: '0 9 * * 1' # Every Monday at 9 AM UTC\n workflow_dispatch: # Allow manual trigger\n\njobs:\n validate-urls:\n runs-on: ubuntu-latest\n name: Validate repository URLs\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v4\n\n - name: Validate URLs\n id: validate-urls\n uses: simeg/urlsup-action@v2.1\n with:\n files: '.' # Check here\n recursive: true # Include sub-dirs\n include-extensions: 'md' # File types to check\n\n timeout-seconds: 5 # Request timeout in seconds\n retry: 2 # Number of retries\n concurrency: 10 # Concurrent requests\n\n allow-status: '200,202,204,429' # Allowed HTTP status codes\n allowlist: 'http://localhost' # Trusted domains\n\n create-annotations: true # Show broken URLs in files\n fail-on-error: true # Fail workflow on broken URLs\n\n user-agent: 'mac-setup/1.0'\n\n"
},
{
"path": ".github/workflows/test.yml",
"content": "name: Test\n\non: [push, pull_request]\n\nenv:\n FORCE_COLOR: 1\n\njobs:\n build:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up node\n uses: actions/setup-node@v4\n with:\n node-version: '22'\n\n - name: Install dependencies\n run: |\n make deps\n\n - name: Test\n run: |\n make ci\n"
},
{
"path": ".gitignore",
"content": "# Dependencies\n/node_modules\n\n# Production\n/build\n\n# Generated files\n.docusaurus\n.cache-loader\n\n# Misc\n.DS_Store\n.env.local\n.env.development.local\n.env.test.local\n.env.production.local\n\nnpm-debug.log*\nyarn-debug.log*\nyarn-error.log*\n"
},
{
"path": ".markdownlint.json",
"content": "{\n \"_comment\": \"Ignore these, they don't fit our style\",\n \"line-length\": false,\n \"no-duplicate-heading\": false,\n \"no-inline-html\": false\n}\n"
},
{
"path": "ANALYTICS_SETUP.md",
"content": "# Analytics Setup Guide\n\nThis document explains how to complete the Google Analytics setup for tracking popular sections.\n\n## Google Analytics 4 Configuration\n\nThe site has been configured with Google Analytics 4 (GA4) integration using the `@docusaurus/plugin-google-gtag` plugin.\n\n### Final Setup Steps\n\n1. **Create a Google Analytics 4 Property**:\n - Go to [Google Analytics](https://analytics.google.com/)\n - Create a new GA4 property for your website\n - Copy the Measurement ID (format: `G-XXXXXXXXXX`)\n\n2. **Update the Configuration**:\n - Edit `docusaurus.config.ts`\n - Replace `G-XXXXXXXXXX` on line 70 with your actual Measurement ID\n\n3. **Verify Installation**:\n - Deploy the site with your tracking ID\n - Check Google Analytics Real-time reports to confirm data collection\n\n## What's Tracked\n\nThe current configuration tracks:\n\n- Page views and navigation\n- User sessions and demographics\n- Popular content sections\n- Search queries (from the search functionality)\n- Traffic sources and referrals\n\n## Privacy Compliance\n\nThe configuration includes `anonymizeIP: true` to comply with privacy regulations by anonymizing visitor IP addresses.\n"
},
{
"path": "LICENSE",
"content": "This content is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/.\n\nThe code is licensed under the MIT License.\nCopyright (c) 2018, Sourabh Bajaj\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "Makefile",
"content": ".PHONY: ci build deploy deps lint serve\n\nYARN\t\t\t= $(shell command -v yarn 2> /dev/null)\nMARKDOWNLINT\t= $(shell command -v ./node_modules/.bin/markdownlint 2> /dev/null)\n\n# This is run on CI to verify linting is OK and that the guide builds\nci: lint build\n\n# Build the Docusaurus site\nbuild:\nifeq ($(YARN),)\n\t$(error \"yarn is not available, please install Yarn\")\nelse\n\t$(YARN) run build\nendif\n\n# Deploy new version of the guide\ndeploy:\n\tsh ./scripts/publish_docusaurus.sh\n\n# Install dependencies\ndeps:\nifeq ($(YARN),)\n\t$(error \"yarn is not available, please install Yarn\")\nelse\n\t$(YARN) install\nendif\n\n# Lint markdown files\nlint:\nifeq ($(MARKDOWNLINT),)\n\t$(error \"markdownlint is not installed, run 'make deps' to install it\")\nelse\n\t@$(MARKDOWNLINT) . --ignore node_modules --ignore build && echo 'All good 👌'\nendif\n\n# Start a development server\nserve:\nifeq ($(YARN),)\n\t$(error \"yarn is not available, please install Yarn\")\nelse\n\t@$(YARN) start || (echo \"❌ Error: 'make serve' failed!\" && echo \"💡 Try running 'make deps' first to install dependencies\" && exit 1)\nendif\n\n"
},
{
"path": "README.md",
"content": "# [macOS Setup Guide](https://sourabhbajaj.com/mac-setup)\n\n[](https://github.com/sb2nov/mac-setup/actions?query=workflow%3ATest) [](https://github.com/sb2nov/mac-setup/actions/workflows/links.yml)\n\nThis guide covers the basics of setting up a development environment on a new\nMac. Whether you are an experienced programmer or not, this guide is intended\nfor everyone to use as a reference for setting up your environment or\ninstalling languages/libraries.\n\n[](https://raw.githubusercontent.com/sb2nov/mac-setup/refs/heads/main/static/assets/intro.gif)\n\nSome environments we will set up are [Node](https://nodejs.org)\n(JavaScript), [Python](https://www.python.org),\n[C++](http://www.cplusplus.com) and [Ruby](https://www.ruby-lang.org).\nEven if you don't program in all of them, they are useful to have as many\ncommand-line tools rely on them. We'll also show you some useful daily use\napplications. As you read and follow these steps, feel free to post any\nfeedback or comments you may have.\n\n## Contributing to the guide\n\nAll contributions to the guide are welcome. Please help add support for other\nlibraries and languages. To make a contribution please use our [contribution\ntemplate](https://github.com/sb2nov/mac-setup/blob/main/.github/CONTRIBUTION_TEMPLATE.md).\n\n**We're looking for more contributors to maintain and extend the\ndocumentation.**\n\n-------------------------------------------------------------------------------\n\nThis guide is [MIT\nlicensed](https://github.com/sb2nov/mac-setup/blob/main/LICENSE) and has been\ngenerated using [Docusaurus](https://docusaurus.io/). Feel free to contribute or\ncreate new issues on [GitHub](https://github.com/sb2nov/mac-setup/issues).\n"
},
{
"path": "docs/apps/index.md",
"content": "---\ntitle: Other Apps\n---\n\n\nHere is a list of apps that are generally good to use and can come in handy in day to day tasks. The apps are separated into 4 broad categories _Developer Tools_, _Productivity Tools_, _Office Apps_ and _Other_.\n\n## Development Tools\n\n- [Brave Browser](https://brave.com/): A privacy-focused browser built on Chromium with built-in ad blocking and full Chrome DevTools.\n- [Google Chrome](https://www.google.com/intl/en/chrome/browser/): Chrome is a developer friendly browser with powerful development tools built in to it.\n- [Warp](https://www.warp.dev/): A modern terminal built on Rust with AI-powered command suggestions and collaborative features.\n- [Cursor](https://www.cursor.com/): An AI-powered code editor built on VS Code.\n- [Zed](https://zed.dev/): A high-performance code editor built in Rust with real-time collaboration.\n- [GitHub Desktop](https://desktop.github.com/): A GUI for Git that simplifies your development workflow.\n- [Valentina Studio](http://www.valentina-db.com/en/valentina-studio-overview): Valentina Studio is a GUI to create, administer and query MySQL, Postgres and SQLite databases.\n\n## AI Tools\n\n- [Claude](https://claude.ai/): Anthropic's AI assistant desktop app.\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code): An agentic coding tool from Anthropic that lives in your terminal.\n\n## Diff and Merge Tools\n\n[FileMerge](https://developer.apple.com/xcode/features/): A free tool which is already installed on your machine. It might not be the most elegant tool, but it's definitely a solid one that does the job of comparing & merging text.\n\n\n\n[Beyond Compare](http://www.scootersoftware.com/): Not only can you compare text with this tool but it also supports diffing Word and PDF contents. In the Pro Version it also supports merging.\n\n\n\n[Araxis Merge](http://www.araxis.com/merge/): One of the few diff tools that works with more than just text and image files, this one lets you also compare office documents (like MS Word, Excel, PowerPoint, or ODF). A single license is valid for both Windows and Mac.\n\n\n\n[DeltaWalker](https://www.deltawalker.com/): Just like Araxis, this app also lets you compare office files. However, it goes one step further by letting you compare file archives like ZIP, JAR, and TAR files. It also has great performance for comparing folders.\n\n\n\n### Free alternatives\n\n- [P4Merge](http://www.perforce.com/product/components/perforce-visual-merge-and-diff-tools)\n- [DiffMerge](http://www.sourcegear.com/diffmerge/)\n\nBoth of these tools can't compare in terms of features and user interface with their commercial competitors - but make for a valid alternative on Mac, Windows and Linux.\n\n## Productivity\n\n- [1Password](https://1password.com/): Cross platform password management tool.\n- [Raycast](https://www.raycast.com/): An extendable launcher and productivity tool. A modern alternative to Spotlight and Alfred.\n- [Amphetamine](https://apps.apple.com/us/app/amphetamine/id937984704): Stops the machine from going into sleep mode.\n- [AppCleaner](http://www.freemacsoft.net/appcleaner/): Uninstall apps cleanly.\n- [Dropbox](https://www.dropbox.com/): File syncing to the cloud. It syncs files across all devices (laptop, mobile, tablet), and serves as a backup as well!\n- [Google Drive](https://drive.google.com/): File syncing to the cloud too! Google Docs is a popular tool to collaborate with others.\n- [Rectangle](https://github.com/rxhanson/Rectangle): Don't waste time resizing and moving your windows. Rectangle makes this very easy and is open source.\n- [Shottr](https://shottr.cc/): A small, fast, and feature-rich screenshot tool for Mac.\n- [Pocket](https://getpocket.com): Save For Later. Put articles, videos or pretty much anything into Pocket.\n- [Timing](http://timingapp.com/): Keep track of the time you spend with your Mac.\n- [Transmission](http://www.transmissionbt.com/): A fast, easy and free BitTorrent client.\n- [Unarchiver](https://theunarchiver.com/): Compress/Uncompress app. Supported file formats include Zip, Tar-GZip, Tar-BZip2, RAR, 7-zip, LhA, StuffIt and many other old and obscure formats.\n\n## Communication\n\n- [Slack](https://slack.com/): Team messaging and collaboration.\n- [WhatsApp](https://www.whatsapp.com/): Desktop client for WhatsApp messaging.\n- [Spotify](https://www.spotify.com/): Music streaming.\n\n## Office Apps\n\n- [Keynote](http://www.apple.com/mac/keynote/): Create presentations on Mac, this is supposed to be an alternate to PowerPoint.\n- [Microsoft Office](https://www.microsoft.com/en-us/microsoft-365/mac/microsoft-365-for-mac): Microsoft Office for Mac. Includes Microsoft Word, Excel, PowerPoint and Outlook.\n- [Numbers](http://www.apple.com/mac/numbers/): Create spreadsheets on Mac, this is supposed to be an alternate to Excel.\n- [Pages](http://www.apple.com/mac/pages/): Create text files on Mac, this is supposed to be an alternate to Word.\n\n## Other\n\n- [Skim](https://sourceforge.net/projects/skim-app/): Skim is a PDF reader and note-taker for macOS.\n- [SuperDuper](http://www.shirt-pocket.com/SuperDuper/SuperDuperDescription.html): Take backups of your disk and use the backup disk to restore the machine in case of failure.\n- [TimeOut](http://www.dejal.com/timeout/): Scheduled work breaks to prevent stress injuries.\n- [VLC](http://www.videolan.org/vlc/index.html): VLC Media Player. Enough said.\n"
},
{
"path": "docs/apps/octave.md",
"content": "---\ntitle: Octave\n---\n\n\n[Octave](https://octave.org/) is a programming language for scientific computing.\n\n## Prerequisite\n\nYou might need `homebrew-cask`; if you don't have it, refer to [this section](/homebrew/cask).\n\n## Installation\n\n### Homebrew Octave.app\n\n[Octave.app](https://octave-app.org) is a project to distribute GNU Octave as a native Mac GUI application, to make it easier to install and use Octave on macOS. Note this is not an official GNU or GNU Octave project.\nAs this distributes a compiled version of Octave, installation will be much faster.\n\nTo [install using homebrew-cask](https://octave-app.org/#installing-with-homebrew-cask) run:\n\n```sh\nbrew tap octave-app/octave-app\nbrew install --cask octave-app\n```\n\n### Homebrew official\n\nYou can also install Octave from the official Homebrew source using the method below.\n\nInstall `octave` from core Homebrew (which is available by default):\n\n```sh\nbrew install octave\n```\n\n**Note**: If `brew` complains about not having a formula for Octave, the following command should fix it:\n\n```sh\nbrew tap --repair\n```\n\nThe command below upgrades Octave and its dependencies to the latest Homebrew-supported versions:\n\n```sh\nbrew update && brew upgrade\n```\n\nOctave has many dependencies which will be downloaded and installed prior to Octave. **The entire installation process can take a few hours if you are compiling from source.**\n\n**Note:** On Snow Leopard or earlier, Octave requires an X server. You can download one from the [XQuartz project](https://www.xquartz.org/).\n\nYou might find that you need to add:\n\n```sh\nsetenv (\"GNUTERM\", \"X11\")\n```\n\nto your octaverc file, normally located at `/usr/local/share/octave/site/m/startup`.\n"
},
{
"path": "docs/apps/settings.md",
"content": "---\ntitle: App Settings\n---\n\n\nThese settings are optional. Some of them are highly subjective and should not be considered as the best settings. To each is own.\n\n## Airmail\n\n- Add all the accounts into airmail\n- Update icons and signatures for all the accounts\n- Add alias for all the forwarding addresses\n- Change appearance to minimal\n\n## CheatSheet\n\n- System Preferences -> Security and Privacy -> Accessibility -> Check\n\n## DoubleTwist\n\n- Add the music folder to the library\n\n## Spectacle\n\n- Update all major combinations to work with `Shift + Control + 1-9`\n- Remove the key combinations for the other sizes\n- System Preferences -> Security and Privacy -> Accessibility -> Check\n\n## Timing\n\n- System Preferences -> Security and Privacy -> Accessibility -> Check\n"
},
{
"path": "docs/bash-completion.md",
"content": "---\ntitle: Bash Completion\n---\n\n\nBash completion is a bash function that allows you to auto complete commands or\narguments by typing partially commands or arguments, then pressing the [Tab]\nkey. This will help you when writing the bash command in terminal.\n\n## Install Latest Bash\n\nmacOS ships with an outdated version of Bash (3.2). You can install the latest\nversion using Homebrew:\n\n```sh\nbrew install bash\n```\n\nTo use the Homebrew-installed Bash as your default shell, add it to the list of\nallowed shells and set it:\n\n```sh\nsudo sh -c 'echo \"$(brew --prefix)/bin/bash\" >> /etc/shells'\nchsh -s \"$(brew --prefix)/bin/bash\"\n```\n\n## Installation\n\nUse `bash-completion@2`, which is designed for Bash 4.2+ (the version installed\nby Homebrew):\n\n```sh\nbrew install bash-completion@2\n```\n\nFor it to work, add this to your `~/.bash_profile`:\n\n```sh\n[[ -r \"$(brew --prefix)/etc/profile.d/bash_completion.sh\" ]] && . \"$(brew --prefix)/etc/profile.d/bash_completion.sh\"\n```\n\nRestart your bash session:\n\n```sh\nsource ~/.bash_profile\n```\n\n## Usage\n\nOnce you've done this, you can use bash completion by pressing the tab key\ntwice after a command. For example:\n\n```console\n$ git [tab] [tab]\nadd blame cherry-pick config format-patch gui merge push repack rm stage whatchanged\nam branch citool describe fsck help mergetool range-diff replace send-email stash worktree\napply bundle clean diff gc init mv rebase request-pull shortlog status\narchive checkout clone difftool gitk instaweb notes reflog reset show submodule\nbisect cherry commit fetch grep log pull remote revert show-branch tag\n```\n\n## More\n\nYou can list additional completion packages available by typing:\n\n```sh\nbrew search completion\n```\n\nAnd you can install them using `brew install` commands, for example:\n\n```sh\nbrew install docker-completion\n```\n"
},
{
"path": "docs/contributors.md",
"content": "---\ntitle: Contributors\n---\n\nThank you to everyone who has contributed to creating this awesome guide! 🎉\n\nThis project exists thanks to all the people who contribute:\n\n
\n\n**103 contributors** • **653 total contributions**\n\n---\n\n*Want to contribute? Check out our [contribution guidelines](https://github.com/sb2nov/mac-setup/blob/main/.github/CONTRIBUTION_TEMPLATE.md) and help make this guide even better!*\n"
},
{
"path": "docs/cpp.md",
"content": "---\ntitle: C++\n---\n\n\nMake sure you have installed [Xcode Command Line Tools](/xcode). Verify the compiler is available:\n\n```console\n$ c++ --version\nApple clang version 16.0.0 (clang-1600.0.26.6)\nTarget: arm64-apple-darwin24.3.0\nThread model: posix\n```\n\nTo be able to compile files from your terminal you can add the following alias in your shell configuration file (e.g. `~/.zshrc`).\n\n```sh\nalias cppcompile='c++ -std=c++17 -stdlib=libc++'\n```\n\nThen you can run all cpp file directly using `cppcompile main.cpp` and it will use C++17.\n"
},
{
"path": "docs/docker/index.md",
"content": "---\ntitle: Docker\n---\n\n\n[Docker](https://docs.docker.com) is a platform for developers and sysadmins to develop, ship, and run applications. Docker lets you quickly assemble applications from components and eliminates the friction that can come when shipping code. Docker lets you get your code tested and deployed into production as fast as possible.\n\nWith Docker, developers can build any app in any language using any toolchain. \"Dockerized\" apps are completely portable and can run anywhere - colleagues' macOS and Windows laptops, QA servers running Ubuntu in the cloud, and production data center VMs running Red Hat.\n\n## Installation\n\nThe recommended way to use Docker on macOS is via **Docker Desktop**.\n\n### Using Homebrew\n\n```sh\nbrew install --cask docker\n```\n\n### Manual Download\n\nAlternatively, download Docker Desktop from the [official website](https://www.docker.com/products/docker-desktop/).\n\n### Verify Installation\n\nAfter installing and launching Docker Desktop, verify the installation:\n\n```sh\ndocker --version\ndocker run hello-world\n```\n\nYou can find more about Docker in the [documentation](https://docs.docker.com/).\n"
},
{
"path": "docs/docker/tips-and-tricks.md",
"content": "---\ntitle: Tips and Tricks\n---\n\n\nA collection of useful tips and tricks for Docker.\n\n## Delete all containers\n\n**NOTE:** This will remove ALL your containers.\n\n```sh\ndocker container prune\n```\n\nOR, if you're using an older docker client:\n\n```sh\ndocker rm $(docker ps -a -q)\n```\n\n## Delete all untagged containers\n\n```sh\ndocker image prune\n```\n\nOR, if you're using an older docker client:\n\n```sh\ndocker rmi $(docker images | grep '^' | awk '{print $3}')\n```\n\n## See all space Docker take up\n\n```sh\ndocker system df\n```\n\n## Get IP address of running container\n\n```sh\ndocker inspect [CONTAINER ID] | grep -wm1 IPAddress | cut -d '\"' -f 4\n```\n\n## Kill all running containers\n\n```sh\ndocker kill $(docker ps -q)\n```\n"
},
{
"path": "docs/docker/useful-commands.md",
"content": "---\ntitle: Useful Commands\n---\n\n\nHere follows a list of useful Docker commands with useful flags for each\ncommand.\n\n## Table of Contents\n\n1. [`docker build`](#docker-build)\n2. [`docker exec`](#docker-exec)\n3. [`docker images`](#docker-images)\n4. [`docker inspect`](#docker-inspect)\n5. [`docker logs`](#docker-logs)\n6. [`docker ps`](#docker-ps)\n7. [`docker rmi`](#docker-rmi)\n8. [`docker run`](#docker-run)\n9. [Learn More](#learn-more)\n\n## [`docker build`](https://docs.docker.com/engine/reference/commandline/build/)\n\nBuild an image from a Dockerfile.\n\n```sh\ndocker build [DOCKERFILE PATH]\n```\n\n### Example\n\nBuild an image tagged `my-org/my-image` where the Dockerfile can be found at\n`/tmp/Dockerfile`.\n\n```sh\ndocker build -t my-org:my-image -f /tmp/Dockerfile\n```\n\n### Useful flags\n\n- `--file -f` Path where to find the Dockerfile\n- `--force-rm` Always remove intermediate containers\n- `--no-cache` Do not use cache when building the image\n- `--rm` Remove intermediate containers after a successful build (this is\n`true`) by default\n- `--tag -t` Name and optionally a tag in the ‘name:tag’ format\n\n## [`docker exec`](https://docs.docker.com/engine/reference/commandline/exec/)\n\nExecute a command inside a **running** container.\n\n```sh\ndocker exec [CONTAINER ID]\n```\n\n### Example\n\n```sh\ndocker exec [CONTAINER ID] touch /tmp/exec_works\n```\n\n### Useful flags\n\n- `--detach -d` Detached mode: run command in the background\n- `-it` This will not make the container you started shut down immediately, as\nit will create a pseudo-TTY session (`-t`) and keep STDIN open (`-i`)\n\n## [`docker images`](https://docs.docker.com/engine/reference/commandline/images/)\n\nList all downloaded/created images.\n\n```sh\ndocker images\n```\n\n### Useful flags\n\n- `-q` Only show numeric IDs\n\n## [`docker inspect`](https://docs.docker.com/engine/reference/commandline/inspect)\n\nShows all the info of a container.\n\n```sh\ndocker inspect [CONTAINER ID]\n```\n\n## [`docker logs`](https://docs.docker.com/engine/reference/commandline/logs/)\n\nGets logs from container.\n\n```sh\ndocker logs [CONTAINER ID]\n```\n\n### Useful flags\n\n- `--details` Log extra details\n- `--follow -f` Follow log output. Do not stop when end of file is reached, but\nrather wait for additional data to be appended to the input.\n- `--timestamps -t` Show timestamps\n\n## [`docker ps`](https://docs.docker.com/engine/reference/commandline/ps/)\n\nShows information about all running containers.\n\n```sh\ndocker ps\n```\n\n### Useful flags\n\n- `--all -a` Show all containers (default shows just running)\n- `--filter -f` Filter output based on conditions provided, `docker ps -f=\"name=\"example\"`\n- `--quiet -q` Only display numeric IDs\n\n## [`docker rmi`](https://docs.docker.com/engine/reference/commandline/rmi/)\n\nRemove one or more images.\n\n```sh\ndocker rmi [IMAGE ID]\n```\n\n### Useful flags\n\n- `--force -f` Force removal of the image\n\n## [`docker run`](https://docs.docker.com/engine/reference/commandline/run/)\n\nCreates and starts a container in one operation. Could be used to execute a\nsingle command as well as start a long-running container.\n\nExample:\n\n```sh\ndocker run -it ubuntu:latest /bin/bash\n```\n\nThis will start a ubuntu container with the entrypoint `/bin/bash`. Note that\nif you do not have the `ubuntu` image downloaded it will download it before\nrunning it.\n\n### Useful flags\n\n- `-it` This will not make the container you started shut down immediately, as\nit will create a pseudo-TTY session (`-t`) and keep STDIN open (`-i`)\n- `--rm` Automatically remove the container when it exit. Otherwise it will be\nstored and visible running `docker ps -a`.\n- `--detach -d` Run container in background and print container ID\n- `--volume -v` Bind mount a volume. Useful for accessing folders on your local\ndisk inside your docker container, like configuration files or storage that\nshould be persisted (database, logs etc.).\n\n## Learn More\n\nA list of more useful Docker commands can be found in the\n[docker-cheat-sheet](https://github.com/wsargent/docker-cheat-sheet).\n"
},
{
"path": "docs/emacs.md",
"content": "---\ntitle: Emacs\n---\n\n\n[Emacs](https://www.gnu.org/software/emacs/) is a family of text editors that are characterized by their extensibility. The manual for the most widely used variant, GNU Emacs, describes it as the extensible, customizable, self-documenting, real-time display editor.\n\nDevelopment of the first Emacs began in the mid-1970s, and work on its direct descendant, GNU Emacs, continues actively.\n\n## Installation\n\nThere are many Emacs clients on macOS. The recommended version on macOS is Emacs Mac Port, but others are good as well.\n\n### [Emacs Mac port](https://bitbucket.org/mituharu/emacs-mac/overview) (Recommended)\n\nMany useful features are built with Emacs Mac Port, e.g. environment variables, full screen, visual enhancements and so on.\n\nLink the Homebrew tap first.\n\n```sh\nbrew tap railwaycat/emacsmacport\n```\n\n* Method 1: Install with `brew cask`.\n\n```sh\nbrew install --cask emacs-mac\n```\n\n There are three available versions, `emacs-mac`, `emacs-mac-official-icon`, `emacs-mac-spacemacs-icon`.\n\n* Method 2: Install using `brew`.\n\n```sh\nbrew install emacs-mac [options]\n```\n\n\nClick here to see available options: \n\n1. `--with-dbus`, Build with d-bus support\n2. `--with-modules`, Build with dynamic modules support\n3. `--with-xml2`, Build with libxml2 support\n4. `--with-ctags`, Don't remove the ctags executable that emacs provides\n5. `--with-no-title-bars`, Build with a patch for no title bars on frames (--HEAD is not supported)\n6. `--with-natural-title-bar`, Build with a patch for title bar color inferred by your theme (--HEAD is not supported). [More info is provided here](https://github.com/railwaycat/homebrew-emacsmacport/wiki/Natural-Title-Bar)\n7. `--with-official-icon`, Using official Emacs icon\n8. `--with-modern-icon`, Using a modern style Emacs icon by @tpanum\n9. `--with-spacemacs-icon`, Using the spacemacs Emacs icon by Nasser Alshammari\n10. `--with-icon-for-documents`, Using official icon for documents which default open with Emacs\n\n\n\n### [Emacs plus](https://github.com/d12frosted/homebrew-emacs-plus#emacs-plus)\n\nStart off by tapping the official emacs-plus cask.\n\n```sh\nbrew tap d12frosted/emacs-plus\n```\n\nInstall the latest version of Emacs Plus:\n\n```sh\nbrew install emacs-plus [options]\n```\n\nYou can also install specific versions (e.g. `emacs-plus@29`, `emacs-plus@30`).\n\n\nClick here to see available options: \n1. --with-24bit-color: Experimental: build with 24 bit color support\n2. --with-ctags: Don't remove the ctags executable that Emacs provides\n3. --with-dbus: Build with dbus support\n4. --with-mailutils: Build with mailutils support\n5. --with-natural-title-bar: Experimental: use a title bar colour inferred by your theme\n6. --with-no-title-bars: Experimental: build with a patch for no title bars on frames (--HEAD has this built-in via undecorated flag)\n7. --with-x11: Experimental: build with x11 support\n8. --without-cocoa: Build a non-Cocoa version of Emacs\n9. --without-gnutls: Build without gnutls support\n10. --without-imagemagick@6: Build without imagemagick@6 support\n11. --without-librsvg: Build without librsvg support\n12. --without-libxml2: Build without libxml2 support\n13. --without-modules: Build without dynamic modules support\n14. --without-multicolor-fonts: Build without a patch that enables multicolor font support\n15. --without-spacemacs-icon: Build without Spacemacs icon by Nasser Alshammari\n16. --HEAD: Install HEAD version\n\n\n> **Note**: 1) You might want to install [exec-path-from-shell](https://github.com/purcell/exec-path-from-shell) if you are using Emacs plus. It takes care of your environment variables.\n> 2) To have the title bar match your theme background color, consider using instead:\n> `brew install emacs-plus --HEAD --with-natural-title-bars`\n\n## Spacemacs\n\n[Spacemacs](https://github.com/syl20bnr/spacemacs/blob/master/README.md) is a new way to experience Emacs -- a sophisticated and polished set-up focused on ergonomics, mnemonics and consistency.\n\nSpacemacs can be used naturally by both Emacs and Vim users -- you can even mix the two editing styles. Switching easily between input styles makes Spacemacs a great tool for pair-programming.\n\n### Installation\n\n1. If you have an existing Emacs configuration, back it up first:\n\n ```sh\n cd ~\n mv .emacs.d .emacs.d.bak\n mv .emacs .emacs.bak\n ```\n\n Don't forget to backup and _remove_ `~/.emacs` file otherwise Spacemacs\n **WILL NOT** load since that file prevents Emacs from loading the proper\n initialization file.\n\n2. Clone the repository:\n\n ```sh\n git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d\n ```\n\n `master` is the stable branch and it is _immutable_, **DO NOT** make any\n modification to it or you will break the update mechanism. If you want to\n fork Spacemacs safely use the `develop` branch where you handle the update\n manually.\n\n3. (Optional) Install the [Source Code Pro](https://github.com/adobe-fonts/source-code-pro) font.\n\n If you are running in terminal you'll also need to change font settings of\n your terminal.\n\n4. Launch Emacs. Spacemacs will automatically install the packages it requires.\n If you get an error regarding package downloads then you may try to disable\n the HTTPS protocol by starting Emacs with\n\n ```sh\n emacs --insecure\n ```\n\n Or you can set the `dotspacemacs-elpa-https` to `nil` in your dotfile to\n remove the need to start Emacs with `--insecure` argument. You may wish to\n clear out your `.emacs.d/elpa` directory before doing this, so that any\n corrupted packages you may have downloaded will be re-installed.\n\n5. Restart Emacs to complete the installation.\n\n## Purcell's Emacs configuration\n\nThis is [Purcell's](https://github.com/purcell/emacs.d) emacs configuration tree, continually used and tweaked since 2000, and it may be a good starting point for other Emacs users, especially those who are web developers. These days it's somewhat geared towards macOS, but it is known to also work on Linux and Windows.\n\n### Installation\n\nTo install, clone this repository to `~/.emacs.d`, i.e. ensure that the `init.el` contained in this repository ends up at `~/.emacs.d/init.el`:\n\n```sh\ngit clone https://github.com/purcell/emacs.d.git ~/.emacs.d\n```\n\nUpon starting up Emacs for the first time, further third-party packages will be automatically downloaded and installed. If you encounter any errors at that stage, try restarting Emacs, and possibly running `M-x package-refresh-contents` before doing so.\n\n## Doom Emacs\n\n[Doom Emacs](https://github.com/doomemacs/doomemacs) is a configuration framework for GNU Emacs. It can be considered a hacker's starter kit.\n\n### Installation\n\n```sh\ngit clone --depth 1 https://github.com/doomemacs/doomemacs ~/.config/emacs\n~/.config/emacs/bin/doom install\n```\n\nVisit the [documentation](https://github.com/doomemacs/doomemacs/blob/master/docs/getting_started.org) for a more detailed guide on installing and customizing Doom.\n"
},
{
"path": "docs/git/gitignore.md",
"content": "---\ntitle: Git Ignore\n---\n\n\nCreate the file `~/.gitignore` as shown below\n\n```gitignore\n# Folder view configuration files\n.DS_Store\nDesktop.ini\n\n# Thumbnail cache files\n._*\nThumbs.db\n\n# Files that might appear on external disks\n.Spotlight-V100\n.Trashes\n\n# Compiled Python files\n*.pyc\n\n# Compiled C++ files\n*.out\n\n# Application specific files\nvenv\nnode_modules\n.sass-cache\n```\n\nfollowed by running the command below, in terminal:\n\n```sh\ngit config --global core.excludesfile ~/.gitignore\n```\n\nto not track files that are almost always ignored in all Git repositories.\n\nOr simply download [macOS specific .gitignore](https://github.com/github/gitignore/blob/master/Global/macOS.gitignore) maintained by GitHub itself and put contents of it to `~/.gitignore`.\n\n* You can also use a default gitignore using Curl\n\n```sh\ncurl https://raw.githubusercontent.com/github/gitignore/master/Global/macOS.gitignore -o ~/.gitignore\n```\n\n## Generate gitignore\n\nVisit [gitignore.io](https://www.gitignore.io/?templates=macos) and fill it with your needs.\n"
},
{
"path": "docs/git/index.md",
"content": "---\ntitle: Git\n---\n\n\nWhat's a developer without [Git](http://git-scm.com/)? To install, run:\n\n```sh\nbrew install git\n```\n\nWhen done, to test that it installed properly you can run:\n\n```sh\ngit --version\n```\n\nAnd `which git` should output `/opt/homebrew/bin/git` (Apple Silicon) or `/usr/local/bin/git` (Intel).\n\n### Git LFS\n\n[Git Large File Storage](https://git-lfs.github.com/) replaces large files with text pointers inside Git while storing the file contents on a remote server.\n\n```sh\nbrew install git-lfs\ngit lfs install\n```\n\n### GitHub CLI\n\nThe [GitHub CLI](https://cli.github.com/) (`gh`) brings GitHub to your terminal. You can create PRs, review code, manage issues, and more without leaving the command line.\n\n```sh\nbrew install gh\n```\n\nAuthenticate with your GitHub account:\n\n```sh\ngh auth login\n```\n\nNext, we'll define your Git user (should be the same name and email you use for [GitHub](https://github.com/)):\n\n```sh\ngit config --global user.name \"Your Name Here\"\ngit config --global user.email \"your_email@youremail.com\"\n```\n\nThey will get added to your `.gitconfig` file.\n\nTo push code to your GitHub repositories, we will use the recommended HTTPS method. There are also instructions for using SSH. To prevent `git` from asking for your username and password every time you push a commit you can cache your credentials by running the following command, as described in the [instructions](https://docs.github.com/en/get-started/getting-started-with-git/caching-your-github-credentials-in-git).\n\n```sh\ngit config --global credential.helper osxkeychain\n```\n\n## Using HTTPS for GitHub (recommended)\n\nThese instructions are from [the official documentation](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories#cloning-with-https-urls).\n\n### Clone repositories using HTTPS\n\nAfter creating a new repo on GitHub, clone it using:\n\n```sh\ngit clone https://github.com//.git\n```\n\n\\- if you had initialized with a README.\n\nIf you did not, follow the instructions in the section below.\n\n### Set up a new or existing repo with HTTPS for GitHub\n\nIf you are setting up a new repo, add at least one file and commit first. Then, configure the remote and push to GitHub by running:\n\n```sh\ngit remote add origin https://github.com//.git\ngit push -u origin main\n```\n\n## SSH Config for GitHub\n\nThese instructions are for those who wish to use SSH and not HTTPS, and are from [the official documentation](https://docs.github.com/en/authentication/connecting-to-github-with-ssh).\n\n### Check for existing SSH keys\n\nFirst check for existing SSH keys on your computer by running:\n\n```sh\nls -al ~/.ssh\n# Lists the files in your .ssh directory, if they exist\n```\n\nCheck the directory listing to see if you have files named either `id_ed25519.pub` or `id_rsa.pub`. If you don't have either of those files then read on, otherwise skip the next section.\n\n### Generate a new SSH key\n\nIf you don't have an SSH key you need to generate one. To do that you need to run the commands below, and make sure to substitute the placeholder with your email. The default settings are preferred, so when you're asked to enter a file in which to save the key, just press Enter to continue.\n\n```sh\nssh-keygen -t ed25519 -C \"your_email@example.com\"\n# Creates a new ssh key, using the provided email as a label\n```\n\n### Add your SSH key to the ssh-agent\n\nRun the following commands to add your SSH key to the `ssh-agent`.\n\n```sh\neval \"$(ssh-agent -s)\"\n```\n\nModify your `~/.ssh/config` file to automatically load keys into the ssh-agent and store passphrases in your keychain:\n\n```ssh-config\nHost *\n AddKeysToAgent yes\n UseKeychain yes\n IdentityFile ~/.ssh/id_ed25519\n```\n\nThen add your SSH key to the ssh-agent:\n\n```sh\nssh-add --apple-use-keychain ~/.ssh/id_ed25519\n```\n\n### Adding a new SSH key to your GitHub account\n\nThe last step is to let GitHub know about your SSH key so GitHub can recognize you. Run this command to copy your key to your clipboard:\n\n```sh\npbcopy < ~/.ssh/id_ed25519.pub\n```\n\nThen go to GitHub and [input your new SSH key](https://github.com/settings/ssh/new). Paste your key in the \"Key\" text-box and pick a name that represents the computer you're currently using.\n\nWe are now ready to use SSH with GitHub!\n\n### Clone repositories using SSH\n\nAfter creating a new repo on GitHub, clone it using\n\n```sh\ngit clone git@github.com:/.git\n```\n\n\\- if you had initialized with a README.\n\nIf you did not, follow the instructions in the section below.\n\n### Set up a new or existing repo with SSH for GitHub\n\nIf you are setting up a new repo, add at least one file and commit first. Then, configure the remote and push to GitHub by running:\n\n```sh\ngit remote add origin git@github.com:/.git\ngit push -u origin main\n```\n"
},
{
"path": "docs/go.md",
"content": "---\ntitle: Go\n---\n\n\n[Go](https://go.dev) is an open source programming language that makes it easy to build simple, reliable, and efficient software.\n\n## Installation\n\nYou can follow the [official instructions on how to install Go](https://go.dev/doc/install), or you can use Homebrew instead:\n\n```sh\nbrew install go\n```\n\nWhen installed, run `go version` to see the installed version of Go.\n\nAdd `GOPATH/bin` directory to your `PATH` environment variable so you can run Go programs anywhere. Add this to your `~/.zshrc` (or `~/.bash_profile`):\n\n```sh\nexport PATH=$PATH:$(go env GOPATH)/bin\n```\n\n## Write your first program\n\nModern Go uses **modules** for dependency management. Create a new project:\n\n```sh\nmkdir hello && cd hello\ngo mod init hello\n```\n\nCreate a file `main.go`:\n\n```go\npackage main\n\nfunc main() {\n println(\"Hello World!\")\n}\n```\n\nRun the program by running:\n\n```console\n$ go run .\nHello World!\n```\n\n## Import a Go package\n\nWith Go modules, you simply import packages in your code and run `go mod tidy` to download them:\n\n```go\npackage main\n\nimport (\n \"github.com/gorilla/mux\" // Your imported package\n \"net/http\"\n)\n\nfunc yourHandler(w http.ResponseWriter, r *http.Request) {\n w.Write([]byte(\"Gorilla!\\n\"))\n}\n\nfunc main() {\n r := mux.NewRouter()\n // Routes consist of a path and a handler function.\n r.HandleFunc(\"/\", yourHandler)\n\n // Bind to a port and pass our router in\n panic(http.ListenAndServe(\":8000\", r))\n}\n```\n\nThen run:\n\n```sh\ngo mod tidy\n```\n\nThis will automatically download and add the dependency to your `go.mod` file.\n\n## Tooling and learning\n\n### Format your code\n\nGo has a built-in tool that automatically formats Go source code.\n\nTo format a single file run:\n\n```sh\ngofmt -w yourcode.go\n```\n\nYou can also format an entire package:\n\n```sh\ngo fmt path/to/your/package\n```\n\n### Learn more\n\nThe [interactive tutorial](https://go.dev/tour/) will let you learn more about Go.\n"
},
{
"path": "docs/heroku.md",
"content": "---\ntitle: Heroku\n---\n\n\n[Heroku](http://www.heroku.com/) is a [Platform-as-a-Service](http://en.wikipedia.org/wiki/Platform_as_a_service) (PaaS) that simplifies deploying your apps online.\n\n## Installation\n\nAssuming you have a Heroku account ([sign up](https://signup.heroku.com) if you don't), let's install the [Heroku Client](https://devcenter.heroku.com/articles/using-the-cli) for the command-line using Homebrew.\n\n```sh\nbrew install heroku/brew/heroku\n```\n\nThe formula might not have the latest version of the Heroku Client, which is updated pretty often. Let's update it now:\n\n```sh\nheroku update\n```\n\nDon't be afraid to run `heroku update` every now and then to always have the most recent version.\n\n## Setup\n\nLogin to your Heroku account using your email and password:\n\n```sh\nheroku login\n```\n\nIf this is a new account, and since you don't already have a public **SSH key** in your `~/.ssh` directory, it will offer to create one for you. It will also upload the key to your Heroku account, which will allow you to deploy apps from this computer.\n\nIf it didn't offer create the SSH key for you (i.e. your Heroku account already has SSH keys associated with it), you can do so manually by running:\n\n```sh\nmkdir ~/.ssh\nssh-keygen -t rsa\n```\n\nKeep the default file name and skip the passphrase by just hitting Enter both times. Then, add the key to your Heroku account:\n\n```sh\nheroku keys:add\n```\n\n## Usage\n\nOnce your keys are in place and you are authorized, you're ready to deploy apps. Heroku has a [getting started guide](https://devcenter.heroku.com/articles/python), which has all the information you need (the one linked here is for Python, but there is one for every popular language). Heroku uses Git to push code for deployment, so make sure your app is under Git version control.\n\nA cheat sheet for deployment:\n\n```console\n$ cd myapp/\n\n# Create the app on Heroku\n$ heroku create myapp\n\n# Deploy it\n$ git push heroku master\n\n# Check its status\n$ heroku ps\n\n# Check the logs\n$ heroku logs -t\n```\n\nThe [Heroku Dev Center](https://devcenter.heroku.com/) is where you will find more information.\n"
},
{
"path": "docs/homebrew/cask.md",
"content": "---\ntitle: Cask\n---\n\n\n[Homebrew-Cask](https://github.com/Homebrew/homebrew-cask) extends Homebrew and allows you to\ninstall large binary files via a command-line tool. You can for example install\napplications like Brave Browser, Slack, VLC and Rectangle. No more\ndownloading `.dmg` files and dragging them to your Applications folder!\n\n## Search\n\nTo see if an app is available on Cask you can search on the [official Cask\nwebsite](https://formulae.brew.sh/cask/). You can also search in your terminal:\n\n```sh\nbrew search \n```\n\n## Example Applications\n\n### Quick Look plugins\n\nThese plugins add support for the corresponding file type to Mac Quick Look\n(In Finder, mark a file and press Space to start Quick Look). The plugins\nincludes features like syntax highlighting, Markdown rendering, preview of\nJSON, patch files, CSV, ZIP files and more.\n\n```sh\nbrew install --cask \\\n qlmarkdown \\\n betterzip \\\n webpquicklook \\\n suspicious-package \\\n syntax-highlight\n```\n\n### Browsers\n\n```sh\nbrew install --cask brave-browser\n```\n\n### Terminals\n\n```sh\nbrew install --cask warp\n```\n\n### Editors and IDEs\n\n```sh\nbrew install --cask \\\n cursor \\\n zed \\\n sublime-text\n```\n\n### AI Tools\n\n```sh\nbrew install --cask \\\n claude \\\n claude-code\n```\n\n### Productivity\n\n```sh\nbrew install --cask \\\n raycast \\\n rectangle \\\n caffeine \\\n shottr \\\n appcleaner\n```\n\n### Developer Tools\n\n```sh\nbrew install --cask \\\n docker \\\n github \\\n conductor\n```\n\n### Communication and Media\n\n```sh\nbrew install --cask \\\n slack \\\n whatsapp \\\n spotify\n```\n\n### Other Useful Apps\n\n```sh\nbrew install --cask \\\n 1password \\\n dropbox \\\n transmission \\\n vlc\n```\n"
},
{
"path": "docs/homebrew/index.md",
"content": "---\ntitle: Homebrew\n---\n\n\n[Homebrew](https://brew.sh/) calls itself _The missing package manager for\nmacOS_ and is an essential tool for any developer.\n\n## Installation\n\nBefore you can run Homebrew you need to have the **Command Line Tools for\nXcode** installed. It include compilers and other tools that will allow you\nto build things from source. You can install it from the terminal\nby running the following:\n\n```sh\nxcode-select --install\n```\n\nTo install Homebrew run the following in a terminal:\n\n```sh\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n```\n\nhit **Enter**, and follow the steps on the screen.\n\n### Setting up your `PATH`\n\nOn Apple Silicon Macs (M1/M2/M3/M4), Homebrew installs to `/opt/homebrew`. The\ninstaller will print instructions to add Homebrew to your `PATH`. Typically you\nneed to add this to your `~/.zprofile` (or `~/.bash_profile` if using Bash):\n\n```sh\neval \"$(/opt/homebrew/bin/brew shellenv)\"\n```\n\nOn Intel Macs, Homebrew installs to `/usr/local` and is generally already on\nyour `PATH`.\n\nThen, to be able to use `brew` you need to start a new terminal session. After that\nyou should make sure everything is working by running:\n\n```sh\nbrew doctor\n```\n\nIf everything is good, you should see no warnings, and a message that you are\n\"ready to brew!\".\n"
},
{
"path": "docs/homebrew/usage.md",
"content": "---\ntitle: Usage\n---\n\n\nTo install a package (or **Formula** in Homebrew vocabulary) simply type:\n\n```sh\nbrew install \n```\n\nTo update Homebrew's directory of formulae, run:\n\n```sh\nbrew update\n```\n\n**Note**: If that command fails you can manually download the directory of\nformulas like this:\n\n```sh\ncd \"$(brew --prefix)/Homebrew/\"\ngit fetch origin\ngit reset --hard origin/main\n```\n\nTo see if any of your formulas need to be updated:\n\n```sh\nbrew outdated\n```\n\nTo update a formula:\n\n```sh\nbrew upgrade \n```\n\nHomebrew keeps older versions of formulas installed on your system, in case you\nwant to roll back to an older version. That is rarely necessary, so you can do\nsome cleanup to get rid of those old versions:\n\n```sh\nbrew cleanup\n```\n\nIf you want to see what formulae Homebrew would delete _without actually\ndeleting them_, you can run:\n\n```sh\nbrew cleanup --dry-run\n```\n\nTo see what you have installed (with their version numbers):\n\n```sh\nbrew list --versions\n```\n\nTo search for formulas you run:\n\n```sh\nbrew search \n```\n\nTo get more information about a formula you run:\n\n```sh\nbrew info \n```\n\nTo uninstall a formula you can run:\n\n```sh\nbrew uninstall \n```\n\n## Recommended Formulas\n\nHere are some useful formulas for enhancing your command-line experience:\n\n### Core Utilities\n\nmacOS ships with outdated or BSD versions of many command-line tools. These formulas install the latest GNU versions:\n\n```sh\nbrew install \\\n coreutils \\\n moreutils \\\n findutils \\\n gnu-sed \\\n grep \\\n wget \\\n bash \\\n base64\n```\n\n> **Note**: GNU tools are installed with a `g` prefix by default (e.g. `gsed`, `gfind`). To use them without the prefix, add their `libexec/gnubin` directories to your `PATH`. For example, Homebrew will display instructions after installing each formula.\n\n### Search Tools\n\n```sh\nbrew install the_silver_searcher\n```\n\n[The Silver Searcher](https://github.com/ggreer/the_silver_searcher) (`ag`) is a code searching tool similar to `ack`, but faster.\n"
},
{
"path": "docs/intro.md",
"content": "---\nslug: /\ntitle: macOS Setup Guide\ndescription: Installing Development environment on macOS\nid: intro\n---\n\n[](https://github.com/sb2nov/mac-setup/actions?query=workflow%3ATest) [](https://github.com/sb2nov/mac-setup/actions/workflows/links.yml)\n\nThis guide covers the basics of setting up a development environment on a new\nMac. Whether you are an experienced programmer or not, this guide is intended\nfor everyone to use as a reference for setting up your environment or\ninstalling languages/libraries.\n\n\n\nSome environments we will set up are [Node](https://nodejs.org)\n(JavaScript), [Python](https://www.python.org),\n[C++](http://www.cplusplus.com) and [Ruby](https://www.ruby-lang.org).\nEven if you don't program in all of them, they are useful to have as many\ncommand-line tools rely on them. We'll also show you some useful daily use\napplications. As you read and follow these steps, feel free to post any\nfeedback or comments you may have.\n\n## Contributing to the guide\n\nAll contributions to the guide are welcome. Please help add support for other\nlibraries and languages. To make a contribution please use our [contribution\ntemplate](https://github.com/sb2nov/mac-setup/blob/main/.github/CONTRIBUTION_TEMPLATE.md).\n\n**We're looking for more contributors to maintain and extend the\ndocumentation.**\n\n---\n\nThis guide is [MIT\nlicensed](https://github.com/sb2nov/mac-setup/blob/main/LICENSE) and has been\ngenerated using [Docusaurus](https://docusaurus.io/). Feel free to contribute or\ncreate new issues on [GitHub](https://github.com/sb2nov/mac-setup/issues).\n"
},
{
"path": "docs/iterm/ack.md",
"content": "---\ntitle: ack\n---\n\n\n`ack` is a search tool designed for code. It's built to be a replacement for\n`grep` with higher speed and more options.\n\n## Installation\n\nTo install the latest version, use homebrew.\n\n```sh\nbrew install ack\n```\n\n## Why use `ack` over `grep`\n\n- Faster\n- Skips unimportant files by default\n- It searches recursively by default\n- Customizable\n\n## Usage\n\n```sh\nack [OPTION]... PATTERN [FILES OR DIRECTORIES]\n```\n\nLet's say you want to find all JavaScript files that are using the module\n`pancakes` in your project, with `ack` it's as easy as\n\n```sh\nack --js pancakes\n```\n\nOr you may want to find all files that _does not_ contain the word _brew_\n\n```sh\nack -L brew\n```\n\n## Customization\n\nYou can customize `ack` to behave the way you want it to, this configuration i\ns stored in `/.ackrc`.\n\nFor example, you can add a custom type to use as a flag when searching. The\nfollowing configuration will allow you to only search in `.md`, `.mkd` and\n`.markdown` files using the `--markdown` flag.\n\n```sh\n--type-set=markdown=.md,.mkd,.markdown\n```\n\nYou can also tell ack to always sort and use colors in the result.\n\n```sh\n--sort-files\n--color\n```\n\nTo see what configuration `ack` uses you can use the `dump` flag.\n\n```sh\nack --dump\n```\n\n## Alternatives to `ack`\n\n### The Silver Searcher\n\n[The Silver Searcher](https://github.com/ggreer/the_silver_searcher) (`ag`) is a code searching tool similar to `ack`, with a focus on speed.\n\n```sh\nbrew install the_silver_searcher\n```\n\nUsage is similar to `ack`:\n\n```sh\nag pancakes\n```\n"
},
{
"path": "docs/iterm/fzf.md",
"content": "---\ntitle: fzf\n---\n\n\n[`fzf`](https://github.com/junegunn/fzf) is a general-purpose command-line\nfuzzy finder. On it's own it's not very useful but when combined with other\ntools it becomes super powerful.\n\n## Installation\n\nUse [Homebrew](/homebrew) to\ninstall `fzf`:\n\n```sh\nbrew install fzf\n```\n\nIf you want to use shell extensions (better shell integration):\n\n```sh\n$(brew --prefix)/opt/fzf/install\n```\n\nwhich gives you:\n\n- Key bindings (`CTRL-T`, `CTRL-R`, and `ALT-C`) (available for _bash_, _zsh_\n and _fish_)\n- Fuzzy auto-completion (available for _bash_ and _zsh_)\n\n## Example Usages\n\nAdd any of these functions to your shell configuration file and apply the\nchanges to try them out. Or just paste the function in your terminal if you\njust want to try it out without saving it.\n\n```sh\n# fd - cd to selected directory\nfd() {\n local dir\n dir=$(find ${1:-.} -path '*/\\.*' -prune \\\n -o -type d -print 2> /dev/null | fzf +m) &&\n cd \"$dir\"\n}\n```\n\n```sh\n# fh - search in your command history and execute selected command\nfh() {\n eval $( ([ -n \"$ZSH_NAME\" ] && fc -l 1 || history) | fzf +s --tac | sed 's/ *[0-9]* *//')\n}\n```\n\n### Chrome history from your terminal\n\nOpen up your shell config and add following function:\n\n```sh\n# ch - browse chrome history\nch() {\n local cols sep\n cols=$(( COLUMNS / 3 ))\n sep='{::}'\n\n cp -f ~/Library/Application\\ Support/Google/Chrome/Profile\\ 1/History /tmp/h\n\n sqlite3 -separator $sep /tmp/h \\\n \"select substr(title, 1, $cols), url\n from urls order by last_visit_time desc\" |\n awk -F $sep '{printf \"%-'$cols's \\x1b[36m%s\\x1b[m\\n\", $1, $2}' |\n fzf --ansi --multi | sed 's#.*\\(https*://\\)#\\1#' | xargs open\n}\n```\n\n**Note**: Ensure that path to `History` file is correct; read more information\non [StackOverflow](https://stackoverflow.com/a/16742333/1564365).\n"
},
{
"path": "docs/iterm/index.md",
"content": "---\ntitle: iTerm2\n---\n\n\n[iTerm2](http://www.iterm2.com/) is an open source replacement for Apple's Terminal. It's highly customizable and comes with a lot of useful features.\n\n## Installation\n\nUse [Homebrew](/homebrew) to download and install:\n\n```sh\nbrew install --cask iterm2\n```\n\n## Customization\n\n### Colors and Font Settings\n\nHere are some suggested settings you can change or set, **they are all optional**.\n\n- Set hot-key to open and close the terminal to `command + option + i`\n- Go to profiles -> Default -> Terminal -> Check silence bell to disable the terminal session from making any sound\n- Download [one of iTerm2 color schemes](https://github.com/mbadolato/iTerm2-Color-Schemes/tree/master/schemes) and then set these to your default profile colors\n- Change the cursor text and cursor color to yellow make it more visible\n- Change the font to 14pt Source Code Pro Lite. Source Code Pro can be downloaded using [Homebrew](/homebrew) `brew install --cask font-source-code-pro`\n- If you're using BASH instead of ZSH you can add `export CLICOLOR=1` line to your `~/.bash_profile` file for nice coloring of listings\n\n[](https://raw.githubusercontent.com/sb2nov/mac-setup/refs/heads/main/static/assets/Iterm.png)\n\n### MacOS shortcuts ⌘←, ⌘→ and ⌥←, ⌥→\n\nYou might be familiar with shortcuts to skip a word (⌥) or go to start/end of the line (⌘). iTerm is not set up to work with these shortcuts by default but here's how you set them up:\n\nOpen up iTerm2 preferences (⌘ + ,) -> Profiles -> Keys -> Click on `+` icon (add new Keyboard shortcut).\n\n| shortcut | action | Esc+ |\n|:--------:|:--------------------:|:----:|\n| ⌘← | Send Escape Sequence | OH |\n| ⌘→ | Send Escape Sequence | OF |\n| ⌥← | Send Escape Sequence | b |\n| ⌥→ | Send Escape Sequence | f |\n\n### Touch ID sudo workaround\n\nIf you have enabled sudo authentication with Touch ID you will also need to set `Preferences -> Advanced -> Allow sessions to survive logging out and back in` to `No` in iTerm2 preferences.\n"
},
{
"path": "docs/iterm/tree.md",
"content": "---\ntitle: tree\n---\n\n\n`tree` is a recursive directory listing command that produces a depth indented listing of files.\n\n## Installation\n\nTo install the latest version, use homebrew:\n\n```sh\nbrew install tree\n```\n\n## Usage\n\nRunning `tree` will produce output like this:\n\n```console\n$ tree\n\n.\n├── Apps\n│ ├── Octave.md\n│ ├── README.md\n│ ├── Settings.md\n│ ├── araxis-merge.jpg\n│ ├── beyond-compare.png\n│ ├── delta-walker.jpg\n│ ├── filemerge.png\n│ └── kaleidoscope.png\n├── CONTRIBUTING.md\n├── Cpp\n│ └── README.md\n├── Docker\n│ └── README.md\n├── Git\n│ ├── README.md\n│ └── gitignore.md\n└── Go\n └── README.md\n\n5 directories, 14 files\n```\n\nTo limit the recursion you can pass an `-L` flag and specify the maximum depth `tree` will use when searching.\n\n```sh\ntree -L 1\n```\n\nwill output:\n\n```sh\n.\n├── Apps\n├── CONTRIBUTING.md\n├── Cpp\n├── Docker\n├── Git\n└── Go\n\n5 directories, 1 files\n```\n"
},
{
"path": "docs/iterm/zsh.md",
"content": "---\ntitle: Zsh\n---\n\n\nThe Z shell (also known as `zsh`) is a Unix shell that is built on top of `bash`\nand is the **default** shell for macOS (since Catalina). It's highly recommended\nto install a framework with `zsh` as it makes dealing with configuration,\nplugins and themes a lot nicer.\n\nWe've also included an `env.sh` file where we store our aliases, exports, path\nchanges etc. We put this in a separate file to not pollute our main\nconfiguration file too much. This file is found in the bottom of this page.\n\nInstall `zsh` using Homebrew:\n\n```sh\nbrew install zsh\n```\n\nNow you should install a framework, we recommend to use [Oh My Zsh](https://github.com/ohmyzsh/ohmyzsh)\nor [Prezto](https://github.com/sorin-ionescu/prezto). **Note that you should\npick one of them, not use both.**\n\nThe configuration file for `zsh` is called `.zshrc` and lives in your home\nfolder (`~/.zshrc`).\n\n## Oh My Zsh\n\n[Oh My Zsh](https://github.com/ohmyzsh/ohmyzsh) is an open source,\ncommunity-driven framework for managing your `zsh` configuration. It comes\nwith a bunch of features out of the box and improves your terminal experience.\n\nInstall Oh My Zsh:\n\n```sh\nsh -c \"$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)\"\n```\n\nThe installation script should set `zsh` to your default shell, but if it\ndoesn't you can do it manually:\n\n```sh\nchsh -s $(which zsh)\n```\n\n### Configuration\n\nThe out-of-the-box configuration is usable but you probably want to customise\nit to suit your needs. The [Official Wiki](https://github.com/ohmyzsh/ohmyzsh/wiki)\ncontains a lot of useful information if you want to deep dive into what you\ncan do with Oh My Zsh, but we'll cover the basics here.\n\nTo apply the changes you make you need to either **start new shell instance**\nor run:\n\n```sh\nsource ~/.zshrc\n```\n\n#### Plugins\n\nAdd plugins to your shell by adding the name of the plugin to the `plugin`\narray in your `.zshrc`.\n\n```sh\nplugins=(git colored-man-pages colorize pip python brew macos)\n```\n\nYou'll find a list of all plugins on the [Oh My Zsh Wiki](https://github.com/ohmyzsh/ohmyzsh/wiki/Plugins).\nNote that adding plugins can cause your shell startup time to increase.\n\n##### zsh-syntax-highlighting\n\nThe Syntax Highlighting plugin adds beautiful colors to the commands you are typing.\n\nClone the zsh-syntax-highlighting plugin’s repo and copy it to the “Oh My ZSH” plugins directory.\n\n```sh\ngit clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting\n```\n\n##### zsh-autosuggestions\n\nThis plugin auto suggests any of the previous commands. Pretty handy! To select the completion, simply press → key.\n\nClone the zsh-autosuggestions plugin’s repo and copy it to the “Oh My ZSH” plugins directory.\n\n```sh\ngit clone https://github.com/zsh-users/zsh-autosuggestions $ZSH_CUSTOM/plugins/zsh-autosuggestions\n```\n\n##### Enforce Changes\n\nTo apply the changes you make you need to either **start new shell instance**\nor run:\n\n```sh\nsource ~/.zshrc\n```\n\n#### Themes\n\nChanging theme is as simple as changing a string in your configuration file.\nThe default theme is `robbyrussell`. Just change that value to change theme,\nand don't forget to apply your changes.\n\n```sh\nZSH_THEME=pygmalion\n```\n\nYou'll find a list of themes with screenshots on the\n[Oh My Zsh Wiki](https://github.com/ohmyzsh/ohmyzsh/wiki/themes).\n\n## Prezto\n\n[Prezto](https://github.com/sorin-ionescu/prezto) is a configuration framework\nfor `zsh`; it enriches the command line interface environment with sane\ndefaults, aliases, functions, auto completion, and prompt themes.\n\nInstall Prezto:\n\n```sh\ngit clone --recursive https://github.com/sorin-ionescu/prezto.git \"${ZDOTDIR:-$HOME}/.zprezto\"\n```\n\nNext create your `~/.zshrc` by running:\n\n```sh\nsetopt EXTENDED_GLOB\nfor rcfile in \"${ZDOTDIR:-$HOME}\"/.zprezto/runcoms/^README.md(.N); do\n ln -s \"$rcfile\" \"${ZDOTDIR:-$HOME}/.${rcfile:t}\"\n done\n```\n\nFor more information on customisation visit the [GitHub repository for\nPrezto](https://github.com/sorin-ionescu/prezto).\n\n### Modules\n\nAdd modules to Prezto by editing `~/.zpreztorc` and adding the modules as\nstrings to the list:\n\n```sh\nzstyle ':prezto:load' pmodule \\\n 'environment' \\\n 'terminal' \\\n 'editor' \\\n 'history' \\\n 'directory' \\\n 'spectrum' \\\n 'utility' \\\n 'completion' \\\n 'git' \\\n 'syntax-highlighting' \\\n 'history-substring-search' \\\n 'prompt'\n```\n\nAnd don't forget to apply your changes by **starting a new shell instance**.\n\n### Themes\n\nTo list all available themes run:\n\n```sh\nprompt -l\n```\n\nThen open up your config file (`~/.zpreztorc`) and change to the theme you want:\n\n```sh\nzstyle ':prezto:module:prompt' theme 'minimal'\n```\n\n## `env.sh`\n\nTo include `env.sh`, open `~/.zshrc` and add the following:\n\n```sh\nsource ~//env.sh\n```\n\nThis file comes with some pre-defined settings, **they are all optional**.\nPlease review them before you use them as your configuration. These are just\nexamples to show you what you can customise in your shell.\n\n```sh\n#!/bin/zsh\n\n# Add commonly used folders to $PATH\nexport PATH=\"/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin\"\n\n# Specify default editor. Possible values: vim, nano, ed etc.\nexport EDITOR=vim\n\n# File search functions\nfunction f() { find . -iname \"*$1*\" ${@:2} }\nfunction r() { grep \"$1\" ${@:2} -R . }\n\n# Create a folder and move into it in one command\nfunction mkcd() { mkdir -p \"$@\" && cd \"$_\"; }\n\n# Example aliases\nalias cppcompile='c++ -std=c++11 -stdlib=libc++'\nalias g='git'\n```\n"
},
{
"path": "docs/java/index.md",
"content": "---\ntitle: Java\n---\n\n\nUsing Java requires you to install a JDK (\"Java Development Kit\") or JRE (\"Java Runtime Environment\").\nWe'll use a JDK since it can do everything a JRE can, plus more.\n\n## Choosing a JDK\n\nThere are two major JDKs: OpenJDK and the Oracle JDK.\nOpenJDK and Oracle JDK provide the same functionality, and are even built from the same code base.\nThey differ only in their packaging and licensing.\n\nOpenJDK is free for use in all situations.\nOracle JDK requires a paid-for commercial license when used in a production setting.\n\nMost personal users will probably want to use OpenJDK, since it's easier to acquire and install\nand that's what we'll be covering here.\n\n## Installation\n\nFirst you should check if Java is already installed\n\n```sh\njava -version\n```\n\nIf you see a non-empty output like below then Java is already installed on your machine and you are good to go\n\n```sh\nopenjdk version \"21.0.2\" 2024-01-16\nOpenJDK Runtime Environment Homebrew (build 21.0.2)\nOpenJDK 64-Bit Server VM Homebrew (build 21.0.2, mixed mode, sharing)\n```\n\nIf you don't see the output like above then you need to install Java on your system\n\n### Installing OpenJDK\n\n#### Installing OpenJDK using Homebrew\n\n```sh\nbrew install openjdk\n```\n\nIf you're curious, you can list all the available JDK versions via:\n\n```sh\nbrew search jdk\n```\n\nThere will be a lot of options here! If you are not a serious Java developer, don't worry about them, and just use the default `openjdk`.\n\nOnce you've done that, check if Java is correctly installed by running the `java -version` command again.\n\n#### Downloading and installing OpenJDK manually\n\nOpen a web browser and go to [Adoptium](https://adoptium.net/). Select the latest LTS version and download the installer for macOS.\n\nOnce you've done that, check if Java is correctly installed by opening a new Terminal session and running the `java -version` command again.\n"
},
{
"path": "docs/java/sdkman.md",
"content": "---\ntitle: SDKMAN!\n---\n\n\nSDKMAN! is a tool for managing parallel versions of multiple software development kits on most Unix-based systems. It provides a convenient command line interface (CLI) and API for installing, switching, removing and listing candidates.\n\n## Installation\n\nOpen a new terminal and enter:\n\n```sh\n curl -s \"https://get.sdkman.io\" | bash\n```\n\nFollow the instructions on-screen to complete installation.\nNext, open a new terminal or enter:\n\n```sh\nsource \"$HOME/.sdkman/bin/sdkman-init.sh\"\n```\n\nLastly, run the following code snippet to ensure that installation succeeded:\n\n```sh\nsdk version\n```\n\nIf all went well, the version should be displayed. Something like:\n\n```sh\nsdkman 5.0.0+51\n```\n\n## Usage\n\n### Installing an SDK\n\n#### Latest stable\n\nInstall the latest stable version of your SDK of choice (say, Java JDK) by running the following command:\n\n```sh\nsdk install java\n```\n\nYou will see something like the following output:\n\n```sh\nDownloading: java 8u111\n\nIn progress...\n\n######################################################################## 100.0%\n\nInstalling: java 8u111\nDone installing!\n```\n\nNow you will be prompted if you want this version to be set as default.\n\n```sh\nDo you want java 8u111 to be set as default? (Y/n):\nAnswering yes (or hitting enter) will ensure that all subsequent shells opened will have this version of the SDK in use by default.\nSetting java 8u111 as default.\n```\n\n## More commands\n\n* To install a specific version\nqualify the version you require:\n\n```sh\nsdk install scala 2.12.1\n```\n\n* To remove a version\n\n```sh\nsdk uninstall scala 2.11.6\n```\n\nNote that removing a local version will not remove the local installation.\n\n* To list candidates\n\n```sh\nsdk list\n```\n\nMore useful commands and usages can be found at [SDKMAN Usage](https://sdkman.io/usage).\n"
},
{
"path": "docs/jetbrains-ides.md",
"content": "---\ntitle: JetBrains IDEs\n---\n\n\nJetBrains is a company creating tools for developers. Their mission is: _We make professional software development a more productive and enjoyable experience_. In this section a number of IDEs (integrated development environment) as well as a selection of features will be presented.\n\n## Selection of Features\n\n**Note that these features apply to _all_ IDEs mentioned.**\n\n### Shared Key Mappings\n\nIf you use different programming languages you might also use different IDEs/editors. This forces you to learn different key mappings for each individual IDE/editor. With IDEs from JetBrains you only need to learn one key mapping because it's shared between all of their IDEs. If you customize your key mapping you can even export it from one IDE and import in the other one.\n\n### Highly Customizable\n\nNot only can you do lots of customization when it comes to appearance, key mapping and a lot more, you also have plugins. These plugins cover everything from dealing with different file types to using external tools such as Git, Docker, databases, linters and time tracking. JetBrains offer a bunch of their own plugins but you can also develop and publish your own plugins.\n\n### Integrated Tools\n\nTheir IDEs offer so many tools that you never have to leave it if you don't want to. It supports a number of different VCSs (Git, Subversion, Perforce etc.), a terminal window, database browser, debuggers, SSH sessions and more.\n\n### Powerful Refactoring\n\nRename a method used all over your project with a few clicks, or change a method signature in the same way. With statically typed languages like Java and C the refactoring becomes even more powerful.\n\n## Useful Shortcuts\n\n* Search for a file -- `CMD + SHIFT + O`\n* Search for a string -- `CMD + SHIFT + F`\n* Search everything, press `SHIFT` two (2) times\n* Context based action -- `ALT + ENTER` (this one is very contextual, you have to just try it out having your cursor in different places)\n* Refactor this -- `CTRL + T` (place your cursor on what you want to refactor)\n\n## Supported Languages\n\nTheir IDEs support a number of languages, here's a list covering all of the listed ones sorted alphabetically.\n\n* C, C#, C++\n* CSS, Less, Sass, Stylus\n* F#\n* Go\n* Groovy\n* Java\n* JavaScript, TypeScript\n* Kotlin\n* Objective-C\n* PHP\n* Python\n* Ruby\n* Scala\n* SQL\n* Swift\n* VB.NET\n\nThey offer support for more languages using plugins such as Rust, Dart, Haxe, Markdown, Pug/Jade, Slim, Twig and more.\n\n## Installation\n\nGo to [their website](https://www.jetbrains.com/products.html?fromMenu#type=ide) and select what product you'd like to download.\n\nAlternatively, use the [Jetbrains Toolbox App](https://www.jetbrains.com/toolbox-app/) to manage product installations.\n\n## Pricing\n\nIf you're a **student** or an **instructor** (teaching staff members) all IDEs from JetBrains are free to use. You can read more on [their website](https://www.jetbrains.com/student/). If you're not a student they still offer a few free Community Edition (CE) IDEs. Check out [IntelliJ](https://www.jetbrains.com/idea/) (Java) or [PyCharm Edu](https://www.jetbrains.com/pycharm-edu/).\n\nIf you as an individual want to have an [IntelliJ subscription](https://www.jetbrains.com/idea/buy/#edition=personal), for example, it's €14.90/$14.90 every month. Before buying a subscription you should [see if you apply for a free/discounted license](https://www.jetbrains.com/idea/buy/#edition=discounts).\n"
},
{
"path": "docs/latex.md",
"content": "---\ntitle: LaTeX\n---\n\n\n[LaTeX](https://www.latex-project.org/about/), which is pronounced «Lah-tech» or «Lay-tech», is a document preparation system for high-quality typesetting. It is most often used for medium-to-large technical or scientific documents but it can be used for almost any form of publishing.\n\n## Installation\n\nWhen installing LaTex, two following options are given to users:\n\n 1. Install MacTeX with builtin editor (TexLive) - (3.2GB)\n 2. Install BasicTeX only (100MB) + your personal LaTeX editor\n\n### MacTeX vs BasicTeX\n\nMacTeX includes additional programs such as an editor and a BibTeX reference manager that help users to work with TeX outside of the command line. BasicTeX does not include these GUI programs. The trade-off that comes with using BasicTeX is that you will have to download and install additional packages and programs as the need arises- and BasicTeX is so basic that the need will arise. So, after installing BasicTeX you will be faced with the tasks of installing additional programs and installing missing packages.\n\n#### MacTex\n\nDownload [MacTex](http://www.tug.org/mactex/), or use `brew install --cask mactex`.\nYou can read more about MacTex in [What is installed (pdf)](https://www.tug.org/mactex/What_Is_Installed.pdf).\n\nSince MacTex installs a LaTex editor ([TexMaker](http://www.xm1math.net/texmaker/download.html)) already, installing another LaTeX editor is unnecessary.\n\n#### BasicTeX\n\nDownload [BasicTeX](http://tug.org/mactex/morepackages.html), or use `brew install --cask basictex`. You can read more about BasicTex in [BasicTeX (pdf)](https://www.tug.org/mactex/BasicTeX.pdf).\n\nYou may use `tlmgr` to install tools/packages that you need.\n\n> **Note**: You may find CLI tool `tlmgr` cumbersome to use, in that case install GUI for `tlmgr` - [*TeX Live Utility*](https://amaxwell.github.io/tlutility/) - `brew install --cask tex-live-utility`.\n\nNow you should pick a LaTeX editor, here are some to choose from:\n\n 1. [TexMaker](http://www.xm1math.net/texmaker/)\n 2. [TeXstudio](http://texstudio.sourceforge.net/)\n 3. [TeXworks](https://github.com/TeXworks/texworks/releases)\n 4. [TeXShop](http://pages.uoregon.edu/koch/texshop/)\n 5. [LyX](http://www.lyx.org/)\n 6. [TeXlipse](http://texlipse.sourceforge.net/)\n 7. [Sublime Text 3 - LaTeXTools](https://github.com/SublimeText/LaTeXTools)\n 8. [Visual Studio Code - LaTeX-Workshop](https://github.com/James-Yu/LaTeX-Workshop)\n\n> **Note**: You may want to use a PDF reader that watches your PDF files, like Skim (can be installed by `brew install --cask skim` and *Sync* feature can be enabled in Preferences -> Sync).\n"
},
{
"path": "docs/mysql.md",
"content": "---\ntitle: MySQL\n---\n\n\n## Installation\n\nWe will install MySQL using Homebrew, which will also install some header files needed for MySQL bindings in different programming languages (MySQL-Python for one).\n\n```sh\nbrew install mysql\n```\n\n## Usage\n\nTo have launchd start MySQL now and restart at login:\n\n```sh\nbrew services start mysql\n```\n\nOr, if you don't want/need a background service you can just use the `mysql.server` tool:\n\n```sh\nmysql.server start\n```\n\nTo stop it when you are done, run:\n\n```sh\nmysql.server stop\n```\n\nYou can see the different commands available for `mysql.server` with:\n\n```sh\nmysql.server --help\n```\n\nTo connect with the command-line client, run:\n\n```sh\nmysql -uroot\n```\n\n(Use `exit` to quit the MySQL shell)\n\n**Note**: By default, the MySQL user `root` has no password. It doesn't really matter for a local development database. If you wish to change it though, you can use `mysqladmin -u root password 'new-password'`.\n"
},
{
"path": "docs/nodejs.md",
"content": "---\ntitle: Node.js\n---\n\n\nNode.js is a JavaScript runtime built on Chrome's V8 JavaScript engine.\n\n## Installation\n\n### Using Homebrew\n\n```sh\nbrew install node\n```\n\n### Using Node Version Manager (nvm)\n\nDownload and install [nvm](https://github.com/nvm-sh/nvm) by running:\n\n```sh\ncurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash\n```\n\nor via Homebrew:\n\n```sh\nbrew install nvm\n```\n\nThen download Node and select your version by running:\n\n```sh\nsource ~/.bashrc # source your bashrc/zshrc to add nvm to PATH\ncommand -v nvm # check the nvm use message\nnvm install node # install most recent Node stable version\nnvm ls # list installed Node version\nnvm use node # use stable as current version\nnvm ls-remote # list all the Node versions you can install\nnvm alias default node # set the installed stable version as the default Node\n```\n\nSee the [documentation](https://github.com/nvm-sh/nvm#installing-and-updating) for information.\n\n## npm usage\n\nTo install a package:\n\n```sh\nnpm install # Install locally\nnpm install -g # Install globally\n```\n\nTo see what's installed:\n\n```sh\nnpm list [-g]\n```\n\nTo find outdated packages:\n\n```sh\nnpm outdated [-g]\n```\n\nTo upgrade all or a particular package:\n\n```sh\nnpm update [-g] []\n```\n\nTo uninstall a package:\n\n```sh\nnpm uninstall [-g] \n```\n\n## yarn\n\nYarn is another package manager built by Facebook. Yarn stands for Yet Another\nResource Negotiator. It provides similar functionalities as NPM. It is an\nalternative to NPM when installing, uninstalling, and managing package\ndependencies from the NPM registry or GitHub repositories.\n\n```sh\nbrew install yarn\n```\n"
},
{
"path": "docs/postgresql.md",
"content": "---\ntitle: PostgreSQL\n---\n\n\nPostgreSQL is an open source relational database management system (RDBMS). It is the default database for macOS server.\n\n## Installation\n\n```sh\nbrew install postgresql\n```\n\nAfter this, we can test the installation status by checking the version of installed PostgreSQL\n\n```sh\npostgres -V\n```\n\n## Usage\n\n### Start PostgreSQL server\n\nThe recommended way to manage PostgreSQL is via Homebrew services:\n\n```sh\nbrew services start postgresql\n```\n\nThis starts the server now and also sets it to start automatically at login.\n\n### Stop PostgreSQL server\n\n```sh\nbrew services stop postgresql\n```\n\n### Restart PostgreSQL server\n\n```sh\nbrew services restart postgresql\n```\n\n### Start PostgreSQL console\n\n```sh\npsql postgres\n```\n\n### GUI tool\n\n[Postico](https://eggerapps.at/postico2/) is a popular GUI client for PostgreSQL on macOS. Alternatively, [TablePlus](https://tableplus.com/) supports PostgreSQL and many other databases.\n"
},
{
"path": "docs/python/index.md",
"content": "---\ntitle: Python\n---\n\n\nmacOS ships with [Python](https://python.org/) already installed.\nBut you don't want to mess with the system Python (some system tools rely on\nit, etc.), so we'll install our own version(s). There are two ways to install\nPython, (1) Homebrew and (2) Pyenv. If you plan to use multiple versions of\nPython then you should use pyenv.\n\n## Installation\n\n### Homebrew method\n\n```sh\nbrew install python\n```\n\nInstalling Python also installs [pip](https://pip.pypa.io/)\n(and its dependency [Setuptools](https://pypi.org/project/setuptools/)),\nwhich is the package manager for Python. Let's upgrade them both:\n\n```sh\npip3 install --upgrade setuptools\npip3 install --upgrade pip\n```\n\n### Pyenv method\n\n[`pyenv`](https://github.com/pyenv/pyenv) is a Python version manager that can\nmanage and install different versions of Python. Works very much like `rbenv`\nfor Ruby. First, we must install `pyenv` using Homebrew:\n\n```sh\nbrew install pyenv\n```\n\nTo upgrade `pyenv` in the future, use `upgrade` instead of `install`. After\ninstalling, add `pyenv init` to your shell to enable shims and autocompletion.\nAdd the following to your `~/.zshrc` (or `~/.bash_profile` if using Bash):\n\n```sh\neval \"$(pyenv init -)\"\n```\n\nRestart your shell to make sure the path changes take effect.\n\n```sh\nexec $SHELL\n```\n\nYou can now begin using `pyenv`. To list the all available versions of Python,\nincluding Anaconda, Jython, PyPy and Stackless, use:\n\n```sh\npyenv install --list\n```\n\nThen install the desired versions:\n\n```sh\npyenv install 3.12\npyenv install 3.11\n```\n\nUse the `global` command to set global version(s) of Python to be used in all\nshells:\n\n```sh\npyenv global 3.12\npyenv rehash\n```\n\nAll installed Python versions can be\nlocated in `~/.pyenv/versions`. Alternatively, you can run:\n\n```console\n$ pyenv versions\n system (set by /Users/your_account/.pyenv/version)\n* 3.12\n 3.11\n```\n\nThis shows an asterisk `*` next to the currently active version.\n\n### Application-specific Python version\n\nThe `local` command will set local application-specific Python version(s) by\nwriting the version name to a `.python-version` file in the current directory.\nThis version overrides the global version. For example:\n\n```console\n$ cd path/to/directory\n$ pyenv local 3.11\n$ pyenv versions\n system\n 3.12\n* 3.11 (set by /Users/your_account/path/to/directory/.python-version)\n```\n"
},
{
"path": "docs/python/ipython.md",
"content": "---\ntitle: IPython\n---\n\n\n[IPython](http://ipython.org/) is an improved Python shell than the one you get from running `python` in the command-line. It has many cool functions (running Unix commands from the Python shell, easy copy & paste, creating Matplotlib charts in-line etc.). You can find all functions in the [documentation](http://ipython.readthedocs.io/en/stable/).\nIPython is a kernel for Jupyter Notebook. If you are confused IPython with Jupyter, refer to the [Jupyter documentation](https://jupyter.readthedocs.io/en/latest/)\n\n## Installation\n\n```sh\npip install ipython\n```\n\nIf you want a more fine-grained command you can try the following:\n\nFor zsh ->\n\n```sh\npip install 'ipython[zmq,qtconsole,notebook,test]'\n```\n\nFor bash ->\n\n```sh\npip install ipython[zmq,qtconsole,notebook,test]\n```\n"
},
{
"path": "docs/python/numpy.md",
"content": "---\ntitle: Numpy\n---\n\n\nThe [NumPy](https://numpy.org/), [SciPy](https://scipy.org/) and [Matplotlib](https://matplotlib.org/) scientific libraries for Python are always a little tricky to install from source because they have all these dependencies they need to build correctly.\n\nThere are two ways to install these libraries:\n\n* Using `pip`\n\nPython provides an inbuilt package management system `pip` which can be used to install these libraries\n\n```sh\npython -m pip install --user numpy scipy matplotlib ipython jupyter pandas sympy nose\n```\n\n* Using [MacPorts](https://www.macports.org/) and Python 3.5\n\n```sh\nsudo port install py35-numpy py35-scipy py35-matplotlib py35-ipython +notebook py35-pandas py35-sympy py35-nose\n```\n"
},
{
"path": "docs/python/pip.md",
"content": "---\ntitle: Pip\n---\n\n\n[pip](https://pip.pypa.io/) is the package manager for Python. If you installed Python via Homebrew or pyenv, `pip` is already included.\n\n## Verify Installation\n\n```sh\npip3 --version\n```\n\nIf it returns a version `pip` was successfully installed.\n\n## Usage\n\nHere are a few `pip` commands to get you started.\n\nInstall a Python package\n\n```sh\npip3 install \n```\n\nUpgrade a package\n\n```sh\npip3 install --upgrade \n```\n\nSee what's installed\n\n```sh\npip3 freeze\n```\n\nUninstall a package\n\n```sh\npip3 uninstall \n```\n"
},
{
"path": "docs/python/virtualenv.md",
"content": "---\ntitle: Virtualenv\n---\n\n\n[Virtualenv](http://www.virtualenv.org/) is a tool that lets you create an\nisolated Python environment for your project. It creates an environment that\nhas its own installation directories, that doesn’t share dependencies with\nother `virtualenv` environments (and optionally doesn’t access the globally\ninstalled dependencies either). You can even configure what version of Python\nyou want to use for each individual environment. It's very much recommended to\nuse `virtualenv` when dealing with Python applications.\n\n## Installation\n\nTo install `virtualenv` run:\n\n```sh\npip install virtualenv\n```\n\n## Usage\n\nIf you have a project in a directory called `my-project` you can set up\n`virtualenv` for that project by running:\n\n```sh\ncd my-project/\nvirtualenv venv\n```\n\nIf you want your `virtualenv` to also inherit globally installed packages run:\n\n```sh\nvirtualenv venv --system-site-packages\n```\n\nThese commands create a `venv/` directory in your project where all\ndependencies are installed. You need to **activate** it first though (in every\nterminal instance where you are working on your project):\n\n```sh\nsource venv/bin/activate\n```\n\nYou should see a `(venv)` appear at the beginning of your terminal prompt\nindicating that you are working inside the `virtualenv`. Now when you install\nsomething like this:\n\n```sh\npip install \n```\n\nIt will get installed in the `venv/` folder, and not conflict with other\nprojects.\n\nTo leave the virtual environment run:\n\n```sh\ndeactivate\n```\n\n**Important**: Remember to add `venv` to your project's `.gitignore` file so\nyou don't include all of that in your source code.\n\nIt is preferable to install big packages (like Numpy), or packages you always\nuse (like IPython) globally. All the rest can be installed in a `virtualenv`.\n\n## Virtualenvwrapper\n\nTo make it easier to work on multiple projects that has separate environments\nyou can install `virtualenvwrapper`. It's an extension to `virtualenv` and\nmakes it easier to create and delete virtual environments without creating\ndependency conflicts.\n\nTo install `virtualenvwrapper` run:\n\n```sh\npip install virtualenvwrapper\n```\n\nDepending on your setup you might need to install it using `sudo`. Read the\n[installation\ndocumentation](https://virtualenvwrapper.readthedocs.io/en/latest/install.html)\nfor more information.\n\n**Note**: `virtualenvwrapper` keeps all the virtual environments in\n`~/.virtualenv` while `virtualenv` keeps them in the project directory.\n"
},
{
"path": "docs/references.md",
"content": "---\ntitle: References\n---\n\n\nThank you for all the awesome pages and documentation below which helped set this up.\n\n- [Nicolashery](https://github.com/nicolashery/mac-dev-setup)\n- [GitHub Docs](https://docs.github.com)\n- [Docusaurus](https://docusaurus.io/)\n- [Sublime Plugins](https://packagecontrol.io/)\n\n## Contributing\n\nPlease feel free to send [Pull Requests](https://github.com/sb2nov/mac-setup/pulls) fixing any mistakes in the guide or adding additional information.\n"
},
{
"path": "docs/ruby/index.md",
"content": "---\ntitle: Ruby\n---\n\n\nmacOS comes with Ruby installed, but as we don't want to be messing with operating system core files we're going to use the tools `rbenv` and `ruby-build` to manage and install our Ruby versions for our development environment.\n\n## Installation\n\n```sh\nbrew install rbenv ruby-build rbenv-default-gems rbenv-gemset\necho 'eval \"$(rbenv init -)\"' >> ~/Projects/config/env.sh\nsource ~/.zshrc # Apply changes\n```\n\nThe packages we just installed allow us to install different versions of Ruby and specify which version to use on a per project basis and globally. This is very useful to keep a consistent development environment if you need to work in a particular Ruby version.\n\n## Switching versions\n\nWe can install version `3.1.1` and use it as our global version by running:\n\n```sh\nrbenv install 3.1.1\nrbenv global 3.1.1\n```\n\nOn M1 Macs to install older version of Ruby eg. `<2.7.3`, `<2.6.7` you first need to run:\n\n```sh\nexport optflags=\"-Wno-error=implicit-function-declaration\"\n```\n\n## Managing gems in application\n\nBundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed.\n\n```sh\ngem install bundler\necho 'bundler' >> \"$(brew --prefix rbenv)/default-gems\"\n```\n\nWhen starting a Ruby project, you can have sandboxed collections of gems. This lets you have multiple collections of gems installed in different sandboxes, and specify (on a per-application basis) which sets of gems should be used. To have gems install into a sub-folder in your project directory for easy later removal / editing / testing, you can use a project gemset.\n\n```sh\necho '.gems' > /.rbenv-gemsets\n```\n\nYour gems will then get installed in `project/.gems`.\n\n## Configuration\n\nIf you use Google for finding your Gem documentation then you might want to consider saving a bit of time when installing gems by not including the documentation.\n\n```sh\necho 'gem: --no-document' >> ~/.gemrc\n```\n"
},
{
"path": "docs/ruby/rubygems.md",
"content": "---\ntitle: RubyGems\n---\n\n\n[RubyGems](http://rubygems.org/), the Ruby package manager, should be installed on your machine if you previously have installed Ruby. Verify this by running:\n\n```sh\nwhich gem\n```\n\n## Update RubyGems\n\nTo update to its latest version with:\n\n```sh\ngem update --system\n```\n\n## Install gems\n\nTo install a _gem_ (Ruby package), run:\n\n```sh\ngem install \n```\n\nTo install without generating the documentation for each gem (faster):\n\n```sh\ngem install --no-document\n```\n\n## List installed gems\n\n```sh\ngem list\n```\n\nTo check if any installed gems are outdated:\n\n```sh\ngem outdated\n```\n\n## Update installed gems\n\nTo update all gems or a particular gem:\n\n```sh\ngem update []\n```\n\n## Remove old gem versions\n\nRubyGems keeps old versions of gems, so feel free to do some cleaning after updating:\n\n```sh\ngem cleanup\n```\n"
},
{
"path": "docs/rust.md",
"content": "---\ntitle: Rust\n---\n\n\n[Rust](https://www.rust-lang.org) is a systems programming language that runs blazingly fast, prevents segfaults, and guarantees thread safety.\n\n## Installation\n\nFor installation it's advised to use `rustup` as it will (among other things)\nallow you to switch between versions of Rust without having to download\nanything additional.\n\n```sh\nbrew install rustup-init\n```\n\nUse rustup to install the Rust compiler (rustc) and the Rust package manager (cargo).\n\n```sh\nrustup-init\n```\n\nTo verify you can run:\n\n```sh\nrustc --version\n```\n\n[The official documentation on how to install Rust](https://www.rust-lang.org/tools/install).\n"
},
{
"path": "docs/scala.md",
"content": "---\ntitle: Scala\n---\n\n\nMake sure you have Java installed, [the instructions are provided here](/java).\n\n## Installation\n\n```sh\nbrew install scala sbt\n```\n\nVerify the installation:\n\n```sh\nscala -version\n```\n\n## IDE Support\n\nFor Scala development, [IntelliJ IDEA](https://www.jetbrains.com/idea/) with the Scala plugin is the most popular choice. Alternatively, [VS Code](https://code.visualstudio.com/) with the [Metals](https://scalameta.org/metals/) extension provides good Scala support.\n"
},
{
"path": "docs/security.md",
"content": "---\ntitle: Security\n---\n\n\nA development machine should be secured against threats as well as any other machine \\(or even _especially_ a development machine\\). Therefore we will setup\n\n* a firewall\n* disk encryption\n\n## Firewall\n\nIf you run potentially vulnerable software you don't want to be accessed from other machines, consider turning the built-in firewall on. This particularly applies if you develop network software.\n\nTo turn the built-in firewall on:\n\n1. Choose Apple menu \\(\\) > System Settings, then click Network.\n2. Click Firewall.\n3. Turn on Firewall.\n4. Click Options to configure which apps are allowed incoming connections.\n\n> **Note**: On macOS versions before Ventura, this is under System Preferences > Security & Privacy > Firewall.\n\n## Disk Encryption\n\nIf you travel a lot and take your notebook with you \\(including all your source codes\\), you should enable disk encryption.\n\nThe following steps were taken from the [official apple support page](https://support.apple.com/en-us/HT204837) on this:\n\n1. Choose Apple menu \\(\\) > System Settings, then click Privacy & Security.\n2. Scroll down to the FileVault section.\n3. Click Turn On FileVault.\n4. Follow the instructions. You should create a local and offline possibility to disable encryption, when you are asked how to regain access in case of anything.\n\n> **Note**: On newer Apple Silicon Macs, data encryption is enabled by default.\n"
},
{
"path": "docs/sublime-text/index.md",
"content": "---\ntitle: Sublime Text\n---\n\n\n[Sublime Text](http://www.sublimetext.com/) is a widely used editor that describes it self as _a sophisticated text editor for code, markup and prose_.\n\n## Installation\n\nInstall using Homebrew:\n\n```sh\nbrew install --cask sublime-text\n```\n\nOr [download](https://www.sublimetext.com/) the **.dmg** file and drag-and-drop it to the **Applications** folder.\n\n## Use CLI to open file\n\nLet's create a shortcut through which we can launch Sublime Text from the command-line\n\n```sh\nln -s /Applications/Sublime\\ Text.app/Contents/SharedSupport/bin/subl /usr/local/bin/subl\n```\n\nNow you can open a file with `subl myfile.py` or start a new project in the current directory with `subl .`.\n\n## Pricing\n\nSublime Text is not free but it has an unlimited evaluation period that comes with notification pop-ups asking you to buy it, [if you wish to remove the pop-ups you can purchase the tool here](http://www.sublimetext.com/buy).\n"
},
{
"path": "docs/sublime-text/packages.md",
"content": "---\ntitle: Packages\n---\n\n\n## Install Package Control\n\nThe simplest method of installation is through the Sublime Text console. The console is accessed via `View > Show Console` menu. Once open, paste the appropriate Python code for your version of Sublime Text into the console.\n\nThis snippet changes each version and older versions will return an error.\n\nTo get the current versions code, go to [packagecontrol.io](https://packagecontrol.io/installation)\n"
},
{
"path": "docs/sublime-text/plugins.md",
"content": "---\ntitle: Plugins\n---\n\n\n- [Alignment](https://github.com/wbond/sublime_alignment/issues): Easy alignment of multiple selections and multi-line selections\n- [All Autocomplete](https://github.com/alienhard/SublimeAllAutocomplete): Extend Sublime Text 2 auto-completion to find matches in all open files of the current window\n- [AutoFileName](https://github.com/BoundInCode/AutoFileName): Plugin that auto-completes filenames\n- [Bootstrap 3 Snippets](https://github.com/JasonMortonNZ/bs3-sublime-plugin): Twitter Bootstrap 3 snippets plugin for Sublime Text 2 and 3\n- [BracketHighlighter](https://github.com/facelessuser/BracketHighlighter): Bracket and tag highlighter\n- [Dictionaries](https://github.com/SublimeText/Dictionaries): Hunspell UTF8 dictionaries\n- [DictionaryAutoComplete](https://github.com/Zinggi/DictionaryAutoComplete): Plugin that adds dictionary entries to the completions inside comments\n- [EncodingHelper](https://github.com/SublimeText/EncodingHelper): Guess encoding of files, show in status bar, convert to UTF-8 from a variety of encodings\n- [FileDiffs](https://github.com/colinta/SublimeFileDiffs): Shows diffs between the current file, or selection(s) in the current file, and clipboard, another file, or unsaved changes\n- [Git](https://github.com/kemayo/sublime-text-git): Plugin for some Git integration\n- [GitGutter](https://github.com/jisaacks/GitGutter): A Sublime Text 2 and 3 plugin to see git diff in gutter\n- [IndentXML](https://github.com/alek-sys/sublimetext_indentxml): Plugin for re-indenting XML and JSON files\n- [Jade](https://github.com/davidrios/jade-tmbundle): A comprehensive bundle for the Jade template language\n- [Jedi - Python autocompletion](https://github.com/srusskih/SublimeJEDI): Jedi is an autocompletion tool for Python\n- [Jekyll](https://github.com/23maverick23/sublime-jekyll): A plugin for Jekyll static sites\n- [LaTeXTools](https://github.com/SublimeText/LaTeXTools): A LaTeX Plugin for Sublime Text 2 and 3\n- [Python Auto-Complete](https://github.com/eliquious/Python-Auto-Complete): Sublime Text 2 plugin which adds additional auto-completion capability to Python scripts\n- [Python Imports Sorter](https://github.com/vi4m/sublime_python_imports): Sublime Text 2 plugin to organize your imports easily\n- [PythonTraceback](https://github.com/kedder/sublime-python-traceback): Easy navigation in your python tracebacks\n- [SideBarEnhancements](https://github.com/titoBouzout/SideBarEnhancements): Enhancements to sidebar. Files and folders.\n- [SublimeCodeIntel](https://packagecontrol.io/packages/SublimeCodeIntel): Full-featured code intelligence and smart auto-complete engine\n- [SublimeLinter](http://sublimelinter.readthedocs.org/): Interactive code linting framework for Sublime Text 3\n- [SublimeLinter-pep8](https://github.com/SublimeLinter/SublimeLinter-pep8): Linter plugin for python using PEP8\n- [TrailingSpaces](https://github.com/SublimeText/TrailingSpaces): Highlight trailing spaces and delete them in a flash\n"
},
{
"path": "docs/sublime-text/preferences.md",
"content": "---\ntitle: Preferences\n---\n\n\nThis is an example of User Settings for a basic development but please feel free to modify or update as per your choice.\n\n```json\n{\n \"auto_complete_delay\": 5,\n \"auto_complete_selector\": \"source, text\",\n \"color_scheme\": \"Packages/User/Monokai (SL).tmTheme\",\n \"create_window_at_startup\": false,\n \"folder_exclude_patterns\":\n [\n \".svn\",\n \".git\",\n \".DS_Store\",\n \"__pycache__\",\n \"*.pyc\",\n \"*.pyo\",\n \"*.exe\",\n \"*.dll\",\n \"*.obj\",\n \"*.o\",\n \"*.a\",\n \"*.lib\",\n \"*.so\",\n \"*.dylib\",\n \"*.ncb\",\n \"*.sdf\",\n \"*.suo\",\n \"*.pdb\",\n \"*.idb\",\n \"*.psd\"\n ],\n \"font_face\": \"Source Code Pro\",\n \"font_size\": 13,\n \"ignored_packages\":\n [\n \"Markdown\",\n \"Vintage\"\n ],\n \"open_files_in_new_window\": false,\n \"rulers\":\n [\n 80\n ],\n \"translate_tabs_to_spaces\": true,\n \"word_wrap\": true\n}\n```\n"
},
{
"path": "docs/sublime-text/sublime-linter.md",
"content": "---\ntitle: Sublime Linter\n---\n\n\n```json\n{\n \"user\": {\n \"debug\": false,\n \"delay\": 0.25,\n \"error_color\": \"D02000\",\n \"gutter_theme\": \"none\",\n \"gutter_theme_excludes\": [],\n \"lint_mode\": \"background\",\n \"linters\": {\n \"pep8\": {\n \"@disable\": false,\n \"args\": [],\n \"disable\": \"\",\n \"enable\": \"\",\n \"excludes\": [],\n \"ignore\": \"\",\n \"max-line-length\": null,\n \"rcfile\": \"\",\n \"select\": \"\"\n }\n },\n \"mark_style\": \"outline\",\n \"no_column_highlights_line\": false,\n \"paths\": {\n \"linux\": [],\n \"osx\": [\n \"/usr/local/bin/\"\n ],\n \"windows\": []\n },\n \"python_paths\": {\n \"linux\": [],\n \"osx\": [\n \"/usr/local/bin/\"\n ],\n \"windows\": []\n },\n \"rc_search_limit\": 3,\n \"shell_timeout\": 10,\n \"show_errors_on_save\": false,\n \"show_marks_in_minimap\": true,\n \"syntax_map\": {\n \"html (django)\": \"html\",\n \"html (rails)\": \"html\",\n \"html 5\": \"html\",\n \"php\": \"html\",\n \"python django\": \"python\"\n },\n \"warning_color\": \"DDB700\",\n \"wrap_find\": true\n }\n}\n```\n"
},
{
"path": "docs/system-preferences.md",
"content": "---\ntitle: System Settings\n---\n\n## First Time Setup\n\nThe first thing you should do is update your system. To do that go:\n**Apple menu () > System Settings > General > Software Update.**\n\nAlso upgrade your OS to the latest version to have a more secure OS. macOS\nupgrades are usually free so you might as well keep your machine up to date.\n\nIf this is a new computer there are a couple tweaks you could make to the\nSystem Settings. **These settings are all optional, consider them\nsuggestions. Always choose the setting that makes the most sense to you.**\n\n> **Note**: On macOS Ventura (13) and later, \"System Preferences\" has been\n> renamed to \"System Settings\" with a redesigned interface.\n\n## Users & Groups\n\n- _Login Options_ -> _Change fast user switching menu as Icon_\n- Set up _Password_, _Apple ID_, _Picture_, etc.\n\n## Trackpad\n\n- _Point & Click_\n - Enable _Tap to click with one finger_\n - Change _Secondary click_ to _Right corner_\n - Uncheck _Three Finger Drag_\n- _Scroll & Zoom_\n - Uncheck _all_ apart from _Zoom in and out_\n\n## Dock\n\n- _Visual Settings_\n - _Change position_ to _Left_ and _make the size_ of icons _Small_\n- _Other settings_\n - Remove _workspace auto-switching_ by running the following command:\n\n```sh\ndefaults write com.apple.dock workspaces-auto-swoosh -bool NO\nkillall Dock # Restart the Dock process\n```\n\n## Finder\n\n- General\n - Change _New finder window show_ to open in your _Home Directory_\n- Sidebar\n - Add _Home_ and your _Code Directory_\n - Uncheck all _Shared_ boxes\n\n## Menubar\n\n- Remove the _Display_ and _Bluetooth_ icons\n- Change _battery_ to _Show percentage symbols_\n\n## Spotlight\n\n- Uncheck _fonts_, _images_, _files_ etc.\n- Uncheck the _keyboard shortcuts_ as we'll be replacing them with\n [_Raycast_](https://www.raycast.com/)\n\n## Accounts\n\n- Add an _iCloud account_ and sync _Calendar_, _Find my Mac_, _Contacts_ etc.\n\n## User Defaults\n\n- Enable _repeating keys by pressing and holding down keys_: `defaults write\n NSGlobalDomain ApplePressAndHoldEnabled -bool false` (and restart any app\n that you need to repeat keys in)\n- Change the _default folder for screenshots_\n - Open the terminal and create the folder where you would like to store\n your screenshots: `mkdir -p /path/to/screenshots/`\n - Then run the following command: `defaults write com.apple.screencapture\n location /path/to/screenshots/ && killall SystemUIServer`\n\n## Security & Privacy\n\n- Set `Require Password ... after sleep or screen saver begins` to `immediately`\n- Enable FileVault to encrypt your hard drive\n- Turn on Firewall\n"
},
{
"path": "docs/vagrant.md",
"content": "---\ntitle: Vagrant\n---\n\n\nCreate and configure lightweight, reproducible, and portable development environments. [Vagrant](https://www.vagrantup.com/) is a tool for managing virtual machines via a simple to use command line interface.\n\n> **Note**: For most use cases, [Docker](/docker) is now the preferred way to create\n> reproducible development environments. Vagrant is still useful when you need\n> full virtual machines.\n\n## Installation\n\nVagrant uses a virtualization provider. You can use [VirtualBox](https://www.virtualbox.org/) (free) or other providers like VMware or Parallels.\n\n```sh\nbrew install --cask virtualbox\n```\n\nNow install Vagrant:\n\n```sh\nbrew install --cask vagrant\n```\n\n## Usage\n\nAdd the Vagrant box you want to use. We'll use Ubuntu 22.04 for the following example.\n\n```sh\nvagrant box add ubuntu/jammy64\n```\n\nYou can find more boxes at [Vagrant Cloud](https://app.vagrantup.com/boxes/search).\n\nNow create a test directory and `cd` into the test directory. Then we'll initialize the vagrant machine.\n\n```sh\nvagrant init ubuntu/jammy64\n```\n\nNow lets start the machine using the following command.\n\n```sh\nvagrant up\n```\n\nYou can ssh into the machine now.\n\n```sh\nvagrant ssh\n```\n\nHalt the vagrant machine now.\n\n```sh\nvagrant halt\n```\n\nOther useful commands are `suspend` and `destroy`.\n"
},
{
"path": "docs/vim.md",
"content": "---\ntitle: Vim\n---\n\n\n[Vim](http://www.vim.org/) is a highly configurable text editor built to make creating and changing any kind of text very efficient. It is included as \"vi\" with most UNIX systems and with Apple macOS.\n\n## Installation\n\nTo install the latest version, use homebrew:\n\n```sh\nbrew install vim\n```\n\n## The Ultimate vimrc\n\n[The Ultimate vimrc](https://github.com/amix/vimrc) is a collection of vimrc configurations to make easy the usage of vim.\n\nTo download the The Ultimate vimrc, you need to install the git client. If you need install it, use home brew:\n\n```sh\nbrew install git\n```\n\nNow, download the vimrc files:\n\n```sh\ngit clone https://github.com/amix/vimrc.git ~/.vim_runtime\n```\n\nTo install the complete version, run:\n\n```sh\nsh ~/.vim_runtime/install_awesome_vimrc.sh\n```\n\nTo install the _basic_ version, run:\n\n```sh\nsh ~/.vim_runtime/install_basic_vimrc.sh\n```\n\n### Update\n\nTo update the vimrc scripts, run:\n\n```sh\ncd ~/.vim_runtime && git pull --rebase && cd -\n```\n\n## Maximum Awesome\n\n[Maximum Awesome](https://github.com/square/maximum-awesome) is a collection of vim configuration and plugins, like a configuration manager for the vim environment.\n\n### Installation\n\nTo install it, just make a clone of the repository with the git client:\n\n```sh\ngit clone https://github.com/square/maximum-awesome.git\n```\n\nThen install it:\n\n```sh\ncd maximum-awesome\nrake\n```\n\n> **NOTE:** the rake command will install all dependencies needed.\n"
},
{
"path": "docs/visual-studio-code.md",
"content": "---\ntitle: Visual Studio Code\n---\n\n\n[Visual Studio Code](https://code.visualstudio.com/) is a lightweight code editor with support for many programming languages through [extensions](https://code.visualstudio.com/docs/editor/extension-gallery)\n\n## Installation\n\nTo install the latest version, use Homebrew:\n\n```sh\nbrew install --cask visual-studio-code\n```\n\n## macOS integration\n\nLaunch VS Code from the [command line](https://code.visualstudio.com/docs/setup/mac#_launching-from-the-command-line).\n\nAfter that, you can launch VS Code from your terminal:\n\n* `code .` will open VS Code in the current directory\n* `code myfile.txt` will open `myfile.txt` in VS Code\n\n## Useful Extensions\n\n### Python\n\n* [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) - Python code highlighting\n\n To enable auto-formatting on \"Save\", i.e. `⌘ + S`, configure the following:\n\n 1. Change the default formatter to `Black` instead of `Autopep8`. Critical to avoid large diffs. Go to _Preferences_ -> _User Settings_ and update the setting `python.formatter.provider` to `Black`\n\n 2. Enable `Format on Save` Setting: _Editor: Format On Save_ setting on _Code_ -> _Preferences_ -> _Settings_\n\n### JavaScript\n\n* [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint\n) - Useful to check JavaScript errors and helps in auto-formatting the code\n* [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode\n) - JavaScript code formatter\n\n### SQL\n\n* [PostgreSQL formatter](https://marketplace.visualstudio.com/items?itemName=bradymholt.pgformatter)\n\n### Markdown\n\n* [Markdown Preview](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced) - Read Markdown files in VSCode\n\n### GitLens\n\n* [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens\n) - Supercharge the Git capabilities built into VSCode\n\n### Docker\n\n* [Docker](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker) - Create, manage, and debug images from within VSCode\n\n### JSON\n\n* [Paste JSON as Code](https://marketplace.visualstudio.com/items?itemName=quicktype.quicktype) - Infers types from sample JSON data, then outputs strongly typed models and serializers for working with that data in your desired programming language\n\n### Live Server\n\n* [Live Server](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) - Launches a local development server with live reloading for both static and dynamic\n\n### VS Code Icons\n\n* [vscode-icons](https://marketplace.visualstudio.com/items?itemName=vscode-icons-team.vscode-icons) - Adds unique icons to distinguish different file extensions (easier to glance through your directories)\n"
},
{
"path": "docs/xcode.md",
"content": "---\ntitle: Xcode\n---\n\n\n[Xcode](https://developer.apple.com/xcode/) is an integrated development environment for macOS containing a suite of software development tools developed by Apple for developing software for macOS, iOS, watchOS and tvOS.\n\nDownload and install it from the App Store or from [Apple's website](https://developer.apple.com/xcode/).\n\nFor installing Xcode command line tools run:\n\n```sh\nxcode-select --install\n```\n\nIt'll prompt you to install the command line tools. Follow the instructions and you'll have Xcode and Xcode command line tools both installed.\n\n## XQuartz\n\nXQuartz is Apple Inc.'s version of the X server, a component of the X Window System for macOS. It might be useful if you are developing software that uses X11, [it's available for download here](https://www.xquartz.org/) or via Homebrew:\n\n```sh\nbrew install --cask xquartz\n```\n"
},
{
"path": "docusaurus.config.ts",
"content": "import {themes as prismThemes} from 'prism-react-renderer';\nimport type {Config} from '@docusaurus/types';\nimport type * as Preset from '@docusaurus/preset-classic';\n\n// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)\n\nconst config: Config = {\n title: 'macOS Setup Guide',\n tagline: 'Installing Development environment on macOS',\n favicon: 'img/favicon.ico',\n\n // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future\n future: {\n v4: true, // Improve compatibility with the upcoming Docusaurus v4\n },\n\n // Set the production url of your site here\n url: 'https://sourabhbajaj.com',\n // Set the // pathname under which your site is served\n // For GitHub pages deployment, it is often '//'\n baseUrl: '/mac-setup/',\n\n // GitHub pages deployment config.\n // If you aren't using GitHub pages, you don't need these.\n organizationName: 'sb2nov', // Usually your GitHub org/user name.\n projectName: 'mac-setup', // Usually your repo name.\n\n onBrokenLinks: 'throw',\n onBrokenMarkdownLinks: 'warn',\n\n // Even if you don't use internationalization, you can use this field to set\n // useful metadata like html lang. For example, if your site is Chinese, you\n // may want to replace \"en\" with \"zh-Hans\".\n i18n: {\n defaultLocale: 'en',\n locales: ['en'],\n },\n\n presets: [\n [\n 'classic',\n {\n docs: {\n sidebarPath: './sidebars.ts',\n routeBasePath: '/', // Serve the docs at the site's root\n editUrl: 'https://github.com/sb2nov/mac-setup/tree/main/',\n sidebarCollapsed: false,\n },\n blog: false, // Disable the blog plugin\n theme: {\n customCss: './src/css/custom.css',\n },\n } satisfies Preset.Options,\n ],\n ],\n\n plugins: [\n [\n '@easyops-cn/docusaurus-search-local',\n {\n hashed: true,\n language: ['en'],\n highlightSearchTermsOnTargetPage: true,\n explicitSearchResultPath: true,\n indexDocs: true,\n indexBlog: false,\n indexPages: false,\n docsRouteBasePath: '/',\n },\n ],\n [\n '@docusaurus/plugin-google-gtag',\n {\n trackingID: 'G-XXXXXXXXXX', // Replace with your Google Analytics 4 tracking ID\n anonymizeIP: true,\n },\n ],\n ],\n\n themeConfig: {\n // Replace with your project's social card\n image: 'img/docusaurus-social-card.jpg',\n navbar: {\n title: 'macOS Setup Guide',\n items: [\n {\n href: 'https://github.com/sb2nov/mac-setup',\n label: 'GitHub',\n position: 'right',\n },\n {\n href: 'https://sourabhbajaj.com',\n label: 'About',\n position: 'right',\n },\n ],\n },\n footer: {\n style: 'dark',\n links: [\n {\n title: 'Guide',\n items: [\n {\n label: 'System Settings',\n to: '/system-preferences',\n },\n {\n label: 'Homebrew',\n to: '/homebrew',\n },\n {\n label: 'Git',\n to: '/git',\n },\n ],\n },\n {\n title: 'Development Tools',\n items: [\n {\n label: 'Python',\n to: '/python',\n },\n {\n label: 'Node.js',\n to: '/nodejs',\n },\n {\n label: 'Docker',\n to: '/docker',\n },\n ],\n },\n {\n title: 'More',\n items: [\n {\n label: 'GitHub',\n href: 'https://github.com/sb2nov/mac-setup',\n },\n {\n label: 'Issues',\n href: 'https://github.com/sb2nov/mac-setup/issues',\n },\n ],\n },\n ],\n copyright: `This guide is MIT licensed. Built with Docusaurus.`,\n },\n prism: {\n theme: prismThemes.github,\n darkTheme: prismThemes.dracula,\n },\n } satisfies Preset.ThemeConfig,\n};\n\nexport default config;\n"
},
{
"path": "package.json",
"content": "{\n \"name\": \"mac-setup\",\n \"version\": \"0.0.0\",\n \"homepage\": \"https://sourabhbajaj.com/mac-setup/\",\n \"description\": \"Installing Development environment on macOS\",\n \"private\": true,\n \"scripts\": {\n \"start\": \"docusaurus start\",\n \"build\": \"docusaurus build\",\n \"serve\": \"docusaurus serve\",\n \"lint\": \"markdownlint . --ignore node_modules --ignore build\",\n \"install-deps\": \"yarn install\",\n\n \"_below_here_is_from\": \"docusaurus_\",\n \"docusaurus\": \"docusaurus\",\n \"swizzle\": \"docusaurus swizzle\",\n \"deploy\": \"docusaurus deploy\",\n \"clear\": \"docusaurus clear\",\n \"write-translations\": \"docusaurus write-translations\",\n \"write-heading-ids\": \"docusaurus write-heading-ids\",\n \"typecheck\": \"tsc\"\n },\n \"dependencies\": {\n \"@docusaurus/core\": \"3.8.1\",\n \"@docusaurus/plugin-google-gtag\": \"^3.8.1\",\n \"@docusaurus/preset-classic\": \"3.8.1\",\n \"@easyops-cn/docusaurus-search-local\": \"^0.52.1\",\n \"@mdx-js/react\": \"^3.0.0\",\n \"clsx\": \"^2.0.0\",\n \"prism-react-renderer\": \"^2.3.0\",\n \"react\": \"^18.0.0\",\n \"react-dom\": \"^18.0.0\"\n },\n \"devDependencies\": {\n \"markdownlint-cli\": \"0.45.0\",\n \"node-fetch\": \"^3.3.1\",\n\n \"@docusaurus/module-type-aliases\": \"3.8.1\",\n \"@docusaurus/tsconfig\": \"3.8.1\",\n \"@docusaurus/types\": \"3.8.1\",\n \"typescript\": \"~5.6.2\"\n },\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/sb2nov/mac-setup.git\"\n },\n \"keywords\": [\n \"Install\",\n \"Mac\",\n \"macOS\",\n \"Git\",\n \"Docusaurus\",\n \"Setup\",\n \"Instruction\"\n ],\n \"author\": \"Sourabh Bajaj\",\n \"license\": \"MIT\",\n \"bugs\": {\n \"url\": \"https://github.com/sb2nov/mac-setup/issues\"\n },\n \"browserslist\": {\n \"production\": [\n \">0.5%\",\n \"not dead\",\n \"not op_mini all\"\n ],\n \"development\": [\n \"last 3 chrome version\",\n \"last 3 firefox version\",\n \"last 5 safari version\"\n ]\n },\n \"engines\": {\n \"node\": \">=18.0\"\n }\n}\n"
},
{
"path": "scripts/generate_contributors.js",
"content": "#!/usr/bin/env node\n\n/*\n * This script fetches contributors and writes their usernames, profile pictures,\n * and URLs to the Contributors.md file.\n */\n\n// Use native fetch in Node.js 18+ or fallback to node-fetch\nconst fetch = globalThis.fetch || require('node-fetch');\nconst fs = require('fs').promises;\nconst path = require('path');\n\n// Configuration\nconst CONFIG = {\n PAGE_COUNT: 6, // Increased to get more contributors\n FILE_NAME: \"docs/contributors.md\",\n BASE_URL: \"https://api.github.com/repos/sb2nov/mac-setup/contributors?page=\",\n MIN_CONTRIBUTIONS: 1, // Minimum contributions to be included\n AVATAR_SIZE: 80, // Size of GitHub avatar images (larger for better visibility)\n CONTRIBUTORS_PER_ROW: 8, // Number of contributors per row in the grid\n};\n\nconst HEADER = `---\ntitle: Contributors\n---\n\nThank you to everyone who has contributed to creating this awesome guide! 🎉\n\nThis project exists thanks to all the people who contribute:\n\n`;\n\nconst FOOTER = `\n---\n\n*Want to contribute? Check out our [contribution guidelines](https://github.com/sb2nov/mac-setup/blob/main/.github/CONTRIBUTION_TEMPLATE.md) and help make this guide even better!*\n`;\n\n/**\n * Validates that the script is run from the correct directory\n */\nconst validateWorkingDirectory = async () => {\n const cwd = process.cwd();\n\n try {\n await fs.access(path.join(cwd, 'package.json'));\n } catch {\n throw new Error(\"Script must be run from the repository root directory\");\n }\n};\n\n/**\n * Fetches data from a URL with error handling and rate limiting respect\n */\nconst fetchWithRetry = async (url, retries = 3) => {\n for (let i = 0; i < retries; i++) {\n try {\n const response = await fetch(url, {\n headers: {\n 'User-Agent': 'mac-setup-contributors-script',\n // Add GitHub token if available for higher rate limits\n ...(process.env.GITHUB_TOKEN && {\n 'Authorization': `token ${process.env.GITHUB_TOKEN}`\n })\n }\n });\n\n if (!response.ok) {\n if (response.status === 403) {\n console.warn('Rate limit hit, waiting before retry...');\n await new Promise(resolve => setTimeout(resolve, 2000));\n continue;\n }\n throw new Error(`HTTP ${response.status}: ${response.statusText}`);\n }\n\n return await response.json();\n } catch (err) {\n console.warn(`Attempt ${i + 1} failed:`, err.message);\n if (i === retries - 1) throw err;\n await new Promise(resolve => setTimeout(resolve, 1000));\n }\n }\n};\n\n/**\n * Fetches all contributors from GitHub API\n */\nconst fetchContributors = async () => {\n console.log('Fetching contributors...');\n const promises = [];\n\n for (let page = 1; page <= CONFIG.PAGE_COUNT; page++) {\n const url = `${CONFIG.BASE_URL}${page}&per_page=100`;\n promises.push(fetchWithRetry(url));\n }\n\n const results = await Promise.all(promises);\n const allContributors = results.flatMap(contributors => contributors || []);\n\n console.log(`Fetched ${allContributors.length} contributors`);\n return allContributors;\n};\n\n/**\n * Validates and sanitizes contributor data\n */\nconst isValidContributor = (contributor) => {\n const { login, html_url, avatar_url, contributions } = contributor;\n\n // Basic validation\n if (!login || !html_url || !avatar_url) return false;\n\n // Security: prevent script injection\n if (login.includes(' login.includes(pattern))) return false;\n\n // Filter by minimum contributions\n if (contributions < CONFIG.MIN_CONTRIBUTIONS) return false;\n\n return true;\n};\n\n/**\n * Generates Markdown table layout for contributors with profile pictures\n */\nconst generateContributorGrid = (contributors) => {\n const sortedContributors = contributors\n .filter(isValidContributor)\n .sort((a, b) => b.contributions - a.contributions); // Sort by contributions (highest first)\n\n if (sortedContributors.length === 0) {\n return 'No contributors found.';\n }\n\n const COLUMNS = 6; // Number of contributors per row (reduced for better mobile experience)\n let markdown = '';\n\n // Add CSS class for styling\n markdown += '
\\n\\n';\n\n // Create table header (empty headers that will be hidden by CSS)\n markdown += '|' + ' |'.repeat(COLUMNS) + '\\n';\n markdown += '|' + '---|'.repeat(COLUMNS) + '\\n';\n\n // Group contributors into rows\n for (let i = 0; i < sortedContributors.length; i += COLUMNS) {\n const row = sortedContributors.slice(i, i + COLUMNS);\n const rowCells = [];\n\n for (let j = 0; j < COLUMNS; j++) {\n if (j < row.length) {\n const { login, html_url, avatar_url, contributions } = row[j];\n const avatarUrl = `${avatar_url}&s=${CONFIG.AVATAR_SIZE}`;\n\n // Create cell with avatar and username\n const cell = `[](${html_url}) [${login}](${html_url})`;\n rowCells.push(cell);\n } else {\n // Empty cell for incomplete rows\n rowCells.push(' ');\n }\n }\n\n markdown += `| ${rowCells.join(' | ')} |\\n`;\n }\n\n // Close the div wrapper\n markdown += '\\n
\\n';\n\n // Add summary statistics\n const totalContributions = sortedContributors.reduce((sum, c) => sum + c.contributions, 0);\n markdown += `\\n**${sortedContributors.length} contributors** • **${totalContributions} total contributions**\\n`;\n\n return markdown;\n};\n\n/**\n * Writes content to file with error handling\n */\nconst writeToFile = async (content) => {\n try {\n // Ensure directory exists\n const dir = path.dirname(CONFIG.FILE_NAME);\n await fs.mkdir(dir, { recursive: true });\n\n await fs.writeFile(CONFIG.FILE_NAME, content, 'utf8');\n console.log(`✅ Successfully wrote contributors to ${CONFIG.FILE_NAME}`);\n } catch (err) {\n throw new Error(`Failed to write file: ${err.message}`);\n }\n};\n\n/**\n * Checks for GitHub token and provides instructions if missing\n */\nconst checkGitHubToken = () => {\n if (!process.env.GITHUB_TOKEN) {\n console.warn('⚠️ No GitHub token found!');\n console.warn('');\n console.warn('To avoid rate limiting, please set up a GitHub Personal Access Token:');\n console.warn('');\n console.warn('1. Go to: https://github.com/settings/tokens/new');\n console.warn('2. Generate a token with these scopes:');\n console.warn(' - public_repo (or repo if you need private repo access)');\n console.warn(' - read:user');\n console.warn('3. Set the token as an environment variable:');\n console.warn(' export GITHUB_TOKEN=your_token_here');\n console.warn('');\n console.warn('Without a token, you may hit rate limits (60 requests/hour).');\n console.warn('With a token, you get 5,000 requests/hour.');\n console.warn('');\n console.warn('Continuing without token...');\n console.warn('');\n } else {\n console.log('✅ GitHub token found - using authenticated requests');\n }\n};\n\n/**\n * Main execution function\n */\nconst run = async () => {\n try {\n console.log('🚀 Starting contributors generation...');\n\n checkGitHubToken();\n\n await validateWorkingDirectory();\n\n const contributors = await fetchContributors();\n\n if (!contributors || contributors.length === 0) {\n throw new Error('No contributors data received');\n }\n\n console.log('📝 Generating contributor grid...');\n const contributorGrid = generateContributorGrid(contributors);\n\n const fileContent = HEADER + contributorGrid + FOOTER;\n\n await writeToFile(fileContent);\n\n console.log('✨ Contributors page generated successfully!');\n\n } catch (error) {\n console.error('❌ Error:', error.message);\n process.exit(1);\n }\n};\n\n// Handle process termination gracefully\nprocess.on('SIGINT', () => {\n console.log('\\n⚠️ Process interrupted');\n process.exit(1);\n});\n\n// Run the script\nrun();\n"
},
{
"path": "scripts/publish_docusaurus.sh",
"content": "#!/bin/bash -e\n\n# -----------------------------------------------------------------------------\n# publish_docusaurus.sh\n#\n# This script automates building and deploying the Docusaurus documentation\n# site to the `gh-pages` branch.\n#\n# Steps:\n# 1. Verifies that required binaries are available.\n# 2. Aborts if there are any uncommitted changes in the working directory\n# to avoid pushing unrelated changes.\n# 3. Runs the contributor list generator (`scripts/generate_contributors.js`)\n# and commits any changes to `docs/contributors.md` to `main`.\n# 4. Installs dependencies with Yarn and builds the Docusaurus site.\n# 5. Saves the current commit hash (used later in the deploy commit message).\n# 6. Switches to the `gh-pages` branch and rebases with `origin/gh-pages`.\n# 7. Removes previous site artifacts from the repo root on `gh-pages`\n# (HTML/CSS/JS plus `assets`, `img`, `docs`, `static`).\n# 8. Copies the freshly built site from `build/` into the repo root.\n# 9. Cleans untracked directories like `node_modules` and `build` on\n# `gh-pages` to avoid committing extra junk.\n# 10. Stages changes and commits them with a message that includes the short\n# hash of the source commit from `main` (e.g., “Deploy …\n# from main@abc123”).\n# 11. Pushes the update to `origin/gh-pages`.\n# 12. Switches back to `main`.\n#\n# Usage:\n# ./scripts/publish_docusaurus.sh\n#\n# Requirements:\n# - git\n# - yarn\n# - node\n#\n# Note: This script has room for improvement, you could say. It's not an atomic\n# operation to deploy a new version which can lead to some annoyances. We\n# should probably let ChatGPT or some other LLM write a better script but\n# I'll let someone else do that, I've shared enough pain with this script\n# over the years :) /simeg\n#\n# -----------------------------------------------------------------------------\n\nreadonly required_bins=(git yarn node)\n\n# Make sure we don't push unrelated changes\nif [[ $(git status -s | wc -l) -gt 0 ]]; then\n echo \"🚨 You have changed files. Aborting.\"\n exit 1\nfi\n\nfunction is_available {\n command -v \"$1\" >/dev/null 2>&1 ||\n { echo >&2 \"🚨 I require $1 but it's not installed. Aborting.\"; exit 1; }\n}\n\n# Make sure all executables are available on $PATH\nfor cmd in \"${required_bins[@]}\"; do is_available \"$cmd\"; done\necho \"✅ All required packages are available, will continue\"\n\necho \"👥 Updating list of contributors..\"\nnode ./scripts/generate_contributors.js\nif git diff --quiet docs/contributors.md; then\n echo \"👥 No contributor changes to commit\"\nelse\n git add docs/contributors.md\n git commit -m \"Update list of contributors\"\n git push origin main\n echo \"👥 Completed updating list of contributors\"\nfi\n\necho \"📖 Building the guide using Docusaurus..\"\nyarn install\nyarn run build\necho \"📖 Done building guide\"\n\n# Get current commit hash before switching branches\ndeclare MAIN_HASH\nMAIN_HASH=$(git rev-parse --short HEAD)\nreadonly MAIN_HASH\n\ngit checkout gh-pages\ngit pull origin gh-pages --rebase\n\n# Clean old files and copy new build\nrm -rf ./*.html ./*.css ./*.js ./assets ./img ./docs ./static\ncp -R build/* .\n\necho \"🌲 Cleaning untracked files from working tree..\"\ngit clean -fx node_modules\ngit clean -fx node_modules\ngit clean -fx build\necho \"🌲 Done cleaning untracked files\"\n\ngit add .\n\ngit commit -a -m \"Deploy Docusaurus version from main@$MAIN_HASH\"\n\ngit push origin gh-pages\ngit checkout main\n\necho \"😎 Finished building and deploying new version of guide\"\n"
},
{
"path": "sidebars.ts",
"content": "import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';\n\n// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)\n\n/**\n * Creating a sidebar enables you to:\n - create an ordered group of docs\n - render a sidebar for each doc of that group\n - provide next/previous navigation\n\n The sidebars can be generated from the filesystem, or explicitly defined here.\n\n Create as many sidebars as you want.\n */\nconst sidebars: SidebarsConfig = {\n tutorialSidebar: [\n 'intro',\n 'system-preferences',\n 'xcode',\n {\n type: 'category',\n label: 'Homebrew',\n items: ['homebrew/index', 'homebrew/usage', 'homebrew/cask'],\n },\n {\n type: 'category',\n label: 'iTerm2',\n items: ['iterm/index', 'iterm/zsh', 'iterm/tree', 'iterm/fzf', 'iterm/ack'],\n },\n {\n type: 'category',\n label: 'Git',\n items: ['git/index', 'git/gitignore'],\n },\n 'bash-completion',\n 'vim',\n 'emacs',\n {\n type: 'category',\n label: 'Sublime Text',\n items: ['sublime-text/index', 'sublime-text/preferences', 'sublime-text/packages', 'sublime-text/plugins', 'sublime-text/sublime-linter'],\n },\n 'visual-studio-code',\n 'jetbrains-ides',\n 'postgresql',\n {\n type: 'category',\n label: 'Python',\n items: ['python/index', 'python/pip', 'python/virtualenv', 'python/numpy', 'python/ipython'],\n },\n 'mysql',\n 'cpp',\n {\n type: 'category',\n label: 'Java',\n items: ['java/index', 'java/sdkman'],\n },\n 'scala',\n {\n type: 'category',\n label: 'Ruby',\n items: ['ruby/index', 'ruby/rubygems'],\n },\n 'rust',\n 'nodejs',\n 'go',\n 'heroku',\n 'vagrant',\n {\n type: 'category',\n label: 'Docker',\n items: ['docker/index', 'docker/useful-commands', 'docker/tips-and-tricks'],\n },\n 'latex',\n {\n type: 'category',\n label: 'Other Apps',\n items: ['apps/index', 'apps/octave', 'apps/settings'],\n },\n 'security',\n 'references',\n 'contributors',\n ],\n};\n\nexport default sidebars;\n"
},
{
"path": "src/components/HomepageFeatures/index.tsx",
"content": "import type {ReactNode} from 'react';\nimport clsx from 'clsx';\nimport Heading from '@theme/Heading';\nimport styles from './styles.module.css';\n\ntype FeatureItem = {\n title: string;\n Svg: React.ComponentType>;\n description: ReactNode;\n};\n\nconst FeatureList: FeatureItem[] = [\n {\n title: 'Easy to Use',\n Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,\n description: (\n <>\n Docusaurus was designed from the ground up to be easily installed and\n used to get your website up and running quickly.\n \n ),\n },\n {\n title: 'Focus on What Matters',\n Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default,\n description: (\n <>\n Docusaurus lets you focus on your docs, and we'll do the chores. Go\n ahead and move your docs into the docs directory.\n \n ),\n },\n {\n title: 'Powered by React',\n Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,\n description: (\n <>\n Extend or customize your website layout by reusing React. Docusaurus can\n be extended while reusing the same header and footer.\n \n ),\n },\n];\n\nfunction Feature({title, Svg, description}: FeatureItem) {\n return (\n
\n
\n \n
\n
\n {title}\n
{description}
\n
\n
\n );\n}\n\nexport default function HomepageFeatures(): ReactNode {\n return (\n \n
\n
\n {FeatureList.map((props, idx) => (\n \n ))}\n
\n
\n \n );\n}\n"
},
{
"path": "src/components/HomepageFeatures/styles.module.css",
"content": ".features {\n display: flex;\n align-items: center;\n padding: 2rem 0;\n width: 100%;\n}\n\n.featureSvg {\n height: 200px;\n width: 200px;\n}\n"
},
{
"path": "src/css/custom.css",
"content": "/**\n * Any CSS included here will be global. The classic template\n * bundles Infima by default. Infima is a CSS framework designed to\n * work well for content-centric websites.\n */\n\n/* You can override the default Infima variables here. */\n:root {\n --ifm-color-primary: #2e8555;\n --ifm-color-primary-dark: #29784c;\n --ifm-color-primary-darker: #277148;\n --ifm-color-primary-darkest: #205d3b;\n --ifm-color-primary-light: #33925d;\n --ifm-color-primary-lighter: #359962;\n --ifm-color-primary-lightest: #3cad6e;\n --ifm-code-font-size: 95%;\n --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);\n}\n\n/* For readability concerns, you should choose a lighter palette in dark mode. */\n[data-theme='dark'] {\n --ifm-color-primary: #25c2a0;\n --ifm-color-primary-dark: #21af90;\n --ifm-color-primary-darker: #1fa588;\n --ifm-color-primary-darkest: #1a8870;\n --ifm-color-primary-light: #29d5b0;\n --ifm-color-primary-lighter: #32d8b4;\n --ifm-color-primary-lightest: #4fddbf;\n --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);\n}\n\n/* Contributors page styling */\n.contributors-table {\n width: 100% !important;\n max-width: 100% !important;\n margin: 0 !important;\n}\n\n.contributors-table table {\n width: 100% !important;\n table-layout: fixed;\n border-collapse: collapse;\n}\n\n.contributors-table img {\n width: 80px !important;\n height: 80px !important;\n border-radius: 50%;\n object-fit: cover;\n border: 3px solid var(--ifm-color-primary-light);\n transition: transform 0.2s ease;\n}\n\n.contributors-table img:hover {\n transform: scale(1.1);\n border-color: var(--ifm-color-primary);\n}\n\n.contributors-table td {\n text-align: center;\n vertical-align: top;\n padding: 16px 8px;\n word-wrap: break-word;\n min-width: 0;\n width: 16.66%; /* 100% / 6 columns */\n}\n\n.contributors-table a {\n text-decoration: none;\n font-size: 0.9rem;\n font-weight: 500;\n display: block;\n margin-top: 8px;\n color: var(--ifm-color-primary);\n}\n\n.contributors-table a:hover {\n color: var(--ifm-color-primary-dark);\n text-decoration: underline;\n}\n\n/* Remove table borders and header */\n.contributors-table table,\n.contributors-table th,\n.contributors-table td {\n border: none !important;\n}\n\n.contributors-table thead {\n display: none;\n}\n\n/* Responsive design for contributors table */\n@media (max-width: 768px) {\n .contributors-table img {\n width: 60px !important;\n height: 60px !important;\n }\n \n .contributors-table a {\n font-size: 0.8rem;\n }\n \n .contributors-table td {\n padding: 12px 4px;\n }\n}\n\n@media (max-width: 480px) {\n .contributors-table img {\n width: 50px !important;\n height: 50px !important;\n }\n \n .contributors-table a {\n font-size: 0.7rem;\n }\n \n .contributors-table td {\n padding: 8px 2px;\n }\n}\n"
},
{
"path": "src/pages/index.module.css",
"content": "/**\n * CSS files with the .module.css suffix will be treated as CSS modules\n * and scoped locally.\n */\n\n.heroBanner {\n padding: 4rem 0;\n text-align: center;\n position: relative;\n overflow: hidden;\n}\n\n@media screen and (max-width: 996px) {\n .heroBanner {\n padding: 2rem;\n }\n}\n\n.buttons {\n display: flex;\n align-items: center;\n justify-content: center;\n}\n"
},
{
"path": "static/.nojekyll",
"content": ""
},
{
"path": "tsconfig.json",
"content": "{\n // This file is not used in compilation. It is here just for a nice editor experience.\n \"extends\": \"@docusaurus/tsconfig\",\n \"compilerOptions\": {\n \"baseUrl\": \".\"\n },\n \"exclude\": [\".docusaurus\", \"build\"]\n}\n"
}
]