Overview

This site contains documentation for the various Bridge School websites, services and accounts.

Contribute

To make changes to this site, follow the procedures below.

Clone the repository

If you would like to make changes to this site, first clone the repository from Bitbucket (refer to the Bitbucket page for more information on how to clone a Git repository from Bitbucket).

git clone git@bitbucket.org:bridgeschool/bs-docs.git

Install MkDocs

This site is built with MkDocs. Install MkDocs (refer to the MkDocs site for installation instructions). If you're on a Mac and have Homebrew installed, you can install with

brew install mkdocs

Install the theme

We use a third party theme for the docs in order to enable some additional functionality. The theme is based off Material UI. The site is already configured to use it properly, but you'll need to install it locally to make sure that Mkdocs can properly build the pages. You can install it via terminal with the following command:

python -m pip install mkdocs-material

Launch Site

Once MkDocs is installed, you can launch the local site by opening a terminal window, changing directory into the repository and running the following command:

mkdocs serve

This will launch the documentation site locally at 127.0.0.1:8000. If you need to stop the MkDocs server, hit Ctrl+C in the terminal where the server is running.

Make your edits

Once the site is up and running, you can edit files, add files, etc and preview your changes on the local site. Refer to the MkDocs site for documentation on how to use MkDocs.

Note

MkDocs uses the Markdown markup language. Consult the Markdown docs for information on how to use Markdown

Build production files

When you're working locally, Mkdocs updates its local cache to build the site. Before you commit your changes to the repository, you'll need to make sure you build the production site files. You can do that with the following command:

mkdocs build

Push your changes to the repository

Once you are happy with your changes and have run a build, push your changes to the repository:

cd /path/to/repository
git add .
git commit -m "My commit message"
git push origin master

Deploying

Once changes have been pushed to the repository, they can be deployed using the same deployment method as other sites. See Deployment.