sb2nov/mac-setup: a Docusaurus guide for provisioning a new Mac

What sb2nov/mac-setup actually is, and who it is written for

The README describes the project as a guide that "covers the basics of setting up a development environment on a new Mac." It is documentation, not an installer, a script collection, or a package manager wrapper. The homepage is a rendered site at sourabhbajaj.com/mac-setup, and the repository behind it holds the Markdown sources, Docusaurus configuration, and a small set of build scripts.

The intended reader is broad. The README says the guide is "intended for everyone to use as a reference for setting up your environment or installing languages/libraries," which is a deliberate choice: it is not only for someone who already knows what Homebrew is. The named environments are Node, Python, C++ and Ruby, and the README gives a reason for installing all four even if you do not program in them: "many command-line tools rely on them." That is the guide's working premise. It assumes a new or reinstalled Mac, a person at a keyboard, and a willingness to follow steps in order.

What it is not is equally clear from the repository layout. There is no install script at the top level, no shell provisioning file, and no formula. The top-level entries are documentation infrastructure: docs/, src/, static/, sidebars.ts, docusaurus.config.ts, and a Makefile. If you arrived looking for something to run, the README's own framing should redirect you to the site.

The Docusaurus build behind the guide

The project moved off GitBook. The only listed release is 0.1, dated 2014-04-19 and labelled "First draft using Gitbook," while the README now states the guide "has been generated using Docusaurus." The current site is a Docusaurus 3.8.1 build, pinned exactly in package.json, with @docusaurus/preset-classic at the same version and @easyops-cn/docusaurus-search-local for offline search. React 18 and TypeScript 5.6 sit underneath.

This matters for anyone who wants to contribute. Content lives as Markdown under docs/, navigation is declared in sidebars.ts, and site behaviour is configured in docusaurus.config.ts. The package.json scripts are the standard Docusaurus set (start, build, serve, deploy, swizzle, clear) plus two project-specific ones: lint runs markdownlint across the tree while ignoring node_modules and build, and typecheck runs tsc. The Makefile wraps these: make ci runs lint and build together, which is what the comment says CI uses to verify that linting passes and the guide builds.

The Makefile also encodes a dependency assumption. Both the build and deps targets check for yarn and error out with "yarn is not available, please install Yarn" if it is missing. The lint target expects ./node_modules/.bin/markdownlint and tells you to run 'make deps' if it is absent. So the toolchain is yarn plus Node, not npm, despite package.json being perfectly readable by npm.

Installing the guide locally and taking a first look

The README does not give install steps for the guide itself; it points contributors at a contribution template and asks for help maintaining the documentation. The Makefile is where the actual commands live. To get a local copy of the site running, clone the repository, then install dependencies through the Makefile, which delegates to yarn install:

make deps

If yarn is not on your PATH, the target stops immediately with the message "yarn is not available, please install Yarn." That is the expected failure mode, not a bug. Once dependencies are installed, start the development server:

make serve

This runs yarn start, which launches docusaurus start. You should see the Docusaurus dev server come up and the guide render in a browser, with the sidebar generated from sidebars.ts. If the command fails, the Makefile prints "Error: 'make serve' failed!" followed by a suggestion to run make deps first, which is usually the right diagnosis.

Before opening a pull request, run the same check CI runs:

make ci

That target runs lint and build in sequence. The lint step invokes markdownlint with the ignore flags for node_modules and build; if it passes, the Makefile echoes 'All good'. The build step runs yarn run build. A failure in either half is what you would need to fix, and the markdownlint configuration is committed as .markdownlint.json at the repository root.

Where the guide stops being useful

The most important limitation is structural: this is prose. Nothing in the repository verifies that the commands printed in the guide still work on the current macOS release. There is a link-checking workflow, referenced by the "Validate URLs" badge in the README, and a Test workflow, but those check the site's links and build, not whether the instructions produce a working environment. A reader who follows the guide on a machine where a formula was renamed will get an error the guide cannot anticipate.

There is also a maintenance signal worth reading carefully. The README states plainly: "We're looking for more contributors to maintain and extend the documentation." That is an explicit request for help, not a routine footer. The last push to the default branch was on 2026-09-10, and the repository is not archived, so it is being touched. But the only tagged release is from 2014, and the request for maintainers suggests the project is closer to a maintained document than a product with a roadmap.

Finally, the guide is the wrong tool if you need reproducibility. If you are provisioning ten machines or rebuilding a CI image, a documented sequence of manual steps is the wrong artifact. The guide is for a person sitting in front of one Mac, and the README's own framing ("feel free to post any feedback or comments") confirms it is a reading experience, not an automation surface.

How it compares to scripted provisioning

The obvious alternative in this space is a configuration management tool that runs on macOS, such as a Homebrew Bundle file or a shell provisioning script checked into a dotfiles repository. The difference is not quality, it is the unit of work. mac-setup ships instructions a human executes and can read as a tutorial; a Brewfile or provisioning script ships a machine-executable description that either converges or fails, usually without explaining why.

That distinction has practical consequences. A Brewfile can be re-run after a failure and will skip what is already installed; the guide's steps have to be re-read and re-applied by hand. A Brewfile is diffable and reviewable in a pull request when you add a tool; the guide is prose, and the equivalent change is a documentation edit. On the other side, the guide can explain what a tool is for and why the guide installs four language runtimes even when you use one, which no Brewfile does.

A reasonable pattern is to use both: read mac-setup to understand what a fresh Mac needs and in what order, then encode the parts you care about into a script you control. The guide does not offer that encoding, and it does not claim to.

Licence and the cost of keeping the guide current

The README states the guide is MIT licensed, and package.json lists "license": "MIT" with the author as Sourabh Bajaj. The repository metadata, however, reports the licence as NOASSERTION, which typically means GitHub's detector could not classify the LICENSE file automatically. If the licence matters to your use, read the LICENSE file at the repository root rather than trusting either the badge or the metadata. Nothing here is legal advice.

Upgrade cost is mostly on the contributor side, not the reader side. The Docusaurus dependencies are pinned to 3.8.1 for the core packages while plugin-google-gtag and the local search plugin use caret ranges, so a fresh yarn install can pull newer minor versions of those two. The markdownlint CLI is pinned at 0.45.0 in devDependencies, which means lint rules change only when someone bumps that entry deliberately. TypeScript is on ~5.6.2.

For a reader, the ongoing cost is re-checking the guide against your macOS version each time you use it, because the repository does not track which OS release the instructions were last verified against. For a maintainer, the cost is the markdownlint pass plus the Docusaurus build on every change, both of which the Makefile exposes as single commands.

Editorial conclusion

Use mac-setup if you want a readable, MIT-licensed checklist for a fresh Mac and you are willing to follow the guide's own steps rather than run a script. Skip it if you need a repeatable, automated provisioning tool, or if you are setting up a machine for someone who will not read a site. Before adopting it, verify the version of Docusaurus pinned in package.json, run make deps and make serve locally to confirm the guide builds on your machine, and read the docs/ directory for the actual installation steps rather than the README, which is aimed at contributors.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. sb2nov/mac-setup on GitHub