Before adding new content, read CONTRIBUTING.md.
The website is statically built using Hugo. So we have basic templating for generating HTML and the ability to write most files in Markdown.
TypeScript documentation is generated directly from source using TYPEDOC. We
just check the resulting files directly into the repo under ./content/reference/pkg/nodejs.
- Node.js and npm
- Ruby
- Yarn for installing dependencies in package.json
- Hugo
- Go
The website is powered by Hugo.
IMPORTANT. Recent versions of Hugo have bugs in the markdown renderer (Blackfriday) that prevents fenced code from rendering correctly in lists when a language is specified. Many of our tutorials are made up of ordered lists of steps, each step containing a code snippet. Until those bugs are fixed, and Hugo has adopted the version of Blackfriday with the fixes, we'll pin to Hugo v0.55.4. Tracking issue: pulumi#1091
The following commands use the package manager, Homebrew.
If you already have Hugo installed, uninstall it:
brew uninstall hugoInstall Hugo v0.55.4:
brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/cf3219506fd28f7133041b74761e8025418435a3/Formula/hugo.rbTo prevent brew from upgrading Hugo:
brew pin hugobrew install goThe quickest way to install the extended version of Hugo v0.55.4 on your Linux machine is to use wget and the dpkg utility. For confirming your server architecture and post-installation cleanup, see Installing Hugo Using the dpkg utility.
wget https://github.com/gohugoio/hugo/releases/download/v0.55.4/hugo_extended_0.55.4_Linux-64bit.debsudo dpkg -i hugo_extended_0.55.4_Linux-64bit.debIf you wish to use brew on Linux, see Homebrew on Linux.
Download the Linux package from https://golang.org/dl/. Follow installation and setup steps on "Installing Go on Ubuntu".
There are several other Go-based tools to install as well.
go get -u github.com/cbroglie/mustache
go get -u github.com/gobuffalo/packr
go get -u github.com/pkg/errors
go get -u gopkg.in/russross/blackfriday.v2make ensure will run yarn install which resolves project dependencies.
make lint_markdown will run yarn lint-markdown which lints the markdown in the content directory.
make build will generate the website (published to public).
make serve will build the website and serve it to http://localhost:1313.
make test runs a broken link checker tool against http://localhost:1313.
make generate will regenerate the TypeScript documentation if needed, as well as the CLI documentation in content/references/cli. The generated API documentation is placed in the [/content/reference/pkg/nodejs]/content/reference/pkg/nodejs) folder. This is extremely hacky.
The following repos must be peers of docs, should be checked out to an appropriate branch, and should be built before running make generate:
pulumipulumi-awspulumi-azurepulumi-cloudpulumi-gcppulumi-kubernetes- etc.
to update API docs for all Pulumi packages, run the following commands to fetch latest release of each package and rebuild docs into .content/reference/pkg folder:
./scripts/update_repos.sh
./scripts/run_typedoc.shTo update a single package, make sure you have it checked out at the desired release label, and then run:
PKGS=yourpackagename ./scripts/run_typedoc.shDocs for additional packages can be added by updating ./scripts/run_typedoc.sh to include the package, and then updating ./config.toml to include the package in the TOC as a [[menu.reference]] entry.
When changes are merged into master, https://www.pulumi.com/ is automatically deployed. You can use the Travis UI to check on the status of the deployment.
Web design is hard. Documentation is hard. Good web design for documentation is harder.
Examples of other sites and their docs as inspiration: