From 731f26de9a3cf013d5a12daea3176915b1b2f57f Mon Sep 17 00:00:00 2001 From: Kegan Maher Date: Fri, 15 Sep 2023 20:48:58 +0000 Subject: [PATCH] docs: update local devcontainer setup --- docs/README.md | 16 ++++++++-------- docs/running-locally.md | 18 ++++++++++++------ 2 files changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/README.md b/docs/README.md index e3690ff..3d98448 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,17 +10,17 @@ published online at `https://docs.calitp.org/repo-name`. Adapted from [GitHub's documentation][gh-template-repo-howto]. -1. Head to the *generate repository* page for this template: - +1. Head to the _generate repository_ page for this template: + 1. Configure the new repository's details, including the **Owner** (`cal-itp`), **Name**, and **Description** -![Screenshot showing creating a new repository from mkdocs-template](img/new-repo-init.png) + ![Screenshot showing creating a new repository from mkdocs-template](img/new-repo-init.png) 1. Ensure the new repository's visiblity is set to **Public** -![Screenshot showing the new repository's visibility set to Public](img/new-repo-visibility.png) + ![Screenshot showing the new repository's visibility set to Public](img/new-repo-visibility.png) 1. Ensure the checkbox to **Include all branches** is checked -![Screenshot showing the Include all branches checkbox checked](img/new-repo-all-branches.png) + ![Screenshot showing the Include all branches checkbox checked](img/new-repo-all-branches.png) 1. Click **Create repository from template** to finish and create the new repository @@ -30,10 +30,10 @@ Once the above steps are complete and the new repository is ready, it's a good i This includes: -* **Review** the `LICENSE` file and ensure it is appropriate for your new project. If not, update it with a more appropriate +- **Review** the `LICENSE` file and ensure it is appropriate for your new project. If not, update it with a more appropriate license before continuing. -* **Find+Replace** instances of `mkdocs-template` with the name of your new repository. -* **Edit** the `docs/.pages` file to update your site's navigation menu, or delete the file to generate a navigation menu for the +- **Find+Replace** instances of `mkdocs-template` with the name of your new repository. +- **Edit** the `docs/.pages` file to update your site's navigation menu, or delete the file to generate a navigation menu for the site automatically. Read more about the [`mkdocs-awesome-pages-plugin`](https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/#customize-navigation). diff --git a/docs/running-locally.md b/docs/running-locally.md index 6453ddb..35fa36a 100644 --- a/docs/running-locally.md +++ b/docs/running-locally.md @@ -13,7 +13,7 @@ cd mkdocs-template ## Build the image ```bash -docker build -t mkdocs-template -f docs/Dockerfile . +docker build -t mkdocs-template -f .devcontainer/Dockerfile . ``` ## Run a container @@ -24,12 +24,18 @@ docker run -p 8000:8000 mkdocs-template The site should be available at . -## VS Code Remote Containers +## VS Code Devcontainer -This repository comes with a [VS Code Remote Containers](https://code.visualstudio.com/docs/remote/containers) -configuration file. +This repository comes with a [VS Code Devcontainers](https://code.visualstudio.com/docs/remote/containers) configuration. Once you clone the repository locally, simply open it within VS Code, which will -prompt you to re-open the repository within the Remote Container. +prompt you to re-open the repository within the Devcontainer. -Once running inside the Remote Container, the site is available at . +Once the Devcontainer is running, bring up the Command Palette and enter: + +```console +> Tasks: Run Build Task +``` + +To build the site and launch a local server. The site is running on at a randomly assigned port; see the +VS Code `Ports` tab for information.