Skip to content

Commit d2495b6

Browse files
nerda-codesnerda-codes
authored
feat(docs): mkdocs tutorial part two (#4609)
1 parent 706046f commit d2495b6

File tree

1 file changed

+191
-0
lines changed
  • tutorials/deploy-automate-mkdocs-site

1 file changed

+191
-0
lines changed

‎tutorials/deploy-automate-mkdocs-site/index.mdx‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
---
2+
meta:
3+
title: Build and deploy an MkDocs static website with GitHub Actions CI/CD
4+
description: Learn how to build and deploy an MkDocs site using GitHub Actions for CI/CD automation. Streamline your workflow with this step-by-step guide.
5+
content:
6+
h1: Build and deploy an MkDocs static website with GitHub Actions CI/CD
7+
paragraph: Learn how to build and deploy an MkDocs site using GitHub Actions for CI/CD automation. Streamline your workflow with this step-by-step guide.
8+
categories:
9+
- object-storage
10+
tags: mkdocs deployment automation static-site ci-cd github
11+
dates:
12+
validation: 2025-03-13
13+
posted: 2025-03-13
14+
---
15+
16+
This tutorial is the second in a series on building and deploying websites using the Scaleway ecosystem. In the [first tutorial](/tutorials/using-bucket-website-with-mkdocs/), we covered how to configure your website. Now, we will walk you through the process of building and deploying it using GitHub Actions CI/CD, the [Object Storage bucket website](/object-storage/concepts/#bucket-website) feature, and MkDocs.
17+
18+
<Macro id="requirements" />
19+
20+
- A Scaleway account logged into the [console](https://console.scaleway.com)
21+
- [Owner](/iam/concepts/#owner) status or [IAM permissions](/iam/concepts/#permission) allowing you to perform actions in the intended Organization
22+
- [Created a bucket](/object-storage/how-to/create-a-bucket/) and [enabled the bucket website feature](/object-storage/how-to/use-bucket-website/)
23+
- [Created a GitHub repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository) containing Markdown files that will be used to generate documentation
24+
- Admin rights on the GitHub repository to create secrets for storing API keys and other variables
25+
- [Installed Python](https://www.python.org/downloads/)
26+
- [Installed pip](https://pip.pypa.io/en/stable/installation/)
27+
- [Installed MkDocs](https://www.mkdocs.org/user-guide/installation/#installing-mkdocs) locally
28+
- Followed [our MkDocs tutorial](/tutorials/using-bucket-website-with-mkdocs/) or created an MkDocs project
29+
30+
## Setting up your MkDocs project
31+
32+
1. Access the repository of your MkDocs project and make sure that the folder containing your Markdown files is named `docs`.
33+
2. In your `mkdocs.yml` file, add the following content. Make sure you replace `your-website-url` with your website's URL, `your-repository` with the name of your GitHub repository, and `username/your-repository/` with your GitHub username and repository.
34+
```
35+
site_url: https://your-website-url.s3-website.fr-par.scw.cloud
36+
repo_url: https://github.com/your-repository/
37+
repo_name: username/your-repository/
38+
```
39+
3. [Preview your MkDocs project](/tutorials/using-bucket-website-with-mkdocs/#preview-your-website) locally. Make sure your website's content displays as expected and that there are no broken links.
40+
4. Run `mkdocs build` to generate your project's static pages. This will create a folder named `site` in your repository.
41+
5. [Deploy](/tutorials/using-bucket-website-with-mkdocs/#deploy-your-website) your website.
42+
43+
## Configuring an IAM application and policy
44+
45+
1. [Create an IAM application](/iam/how-to/create-application/). For the purpose of this documentation, we are naming our application `doc website GitHub Actions`. This application will allow GitHub Actions to interact with your Object Storage bucket.
46+
2. [Create an IAM policy](/iam/how-to/create-policy/) and select **Application** in the **Select a principal** drop-down.
47+
3. Select your application (`doc website GitHub Actions`) in the **Select or type an application drop-down**, then click **Add rules**.
48+
4. Select the **Access to resources** [scope](/iam/concepts/#scope), select the Scaleway Project containing your bucket in the drop-down, then click **Validate**. You are prompted to add permission sets.
49+
5. Click **Storage** under the **Products** section, select the `ObjectStorageFullAccess` permission set, and click **Validate**.
50+
6. Click **Create policy**.
51+
52+
## Adding statements to your bucket policy
53+
54+
Statements allow you to define who can perform what actions on your bucket. In this section, we will add a statement to allow your IAM application to push content to your bucket, and another one that grants public read access to your website's content.
55+
56+
1. From the Scaleway console side-menu, click **Storage**, then click **Object Storage**.
57+
2. Click your bucket, then click the **Bucket settings** tab.
58+
3. Click **View policy details** in the **Bucket policy** section. You are redirected to the **Bucket policy information** page.
59+
4. Click **Edit policy**. For the purpose of this documentation, we are choosing the **policy generator** method to add [statements](/object-storage/api-cli/bucket-policy/#statement).
60+
5. Tick the **Maintain access to bucket** checkbox.
61+
6. Click **+ Add statement**. We are defining the statement to allow your IAM application to push content to your bucket:
62+
63+
- Enter a unique statement ID describing the purpose of the statement. For example `Allow IAM app to push content`.
64+
- Select `Applications` in the **Principals** drop-down.
65+
- Select your IAM application (`doc website GitHub Actions`) in the **Applications** drop-down.
66+
- Select `s3:PutObject` in the **Actions** drop-down.
67+
- Enter `*` in the the **Resource** field.
68+
69+
7. Click **+ Add statement** again. We are defining the statement that grants public read access to your website's content:
70+
71+
- Enter a unique statement ID describing the purpose of the statement. For example `Grant public read access to website`.
72+
- Select `All principals (*)` in the **Principals** drop-down.
73+
- Select `s3:GetObject` in the **Actions** drop-down.
74+
- Enter `*` in the the **Resource** field. This allows anyone to read objects from your bucket.
75+
8. Click **Save changes**.
76+
77+
## Setting up your GitHub repository
78+
79+
In this section, we will configure a GitHub Actions workflow to automatically build and deploy your documentation.
80+
81+
1. Access your GitHub repository and create a folder named `.github`.
82+
2. Create a folder named `workflows` inside `.github`.
83+
3. Create a file named `deploy-docs.yml` inside `workflows`.
84+
The architecture of your repository should look like the following:
85+
```
86+
documentation-website-repository/
87+
└─ .github/
88+
└─ workflows/
89+
└─ deploy-docs.yml
90+
```
91+
4. Paste the following template into `deploy-docs.yml` and save and merge your changes.
92+
93+
```bash
94+
name: Build and push website documentation
95+
96+
on:
97+
workflow_dispatch:
98+
push:
99+
branches:
100+
- main
101+
- master
102+
permissions:
103+
contents: write
104+
105+
jobs:
106+
deploy:
107+
runs-on: ubuntu-latest
108+
environment: actions
109+
steps:
110+
- name: Check out repository
111+
uses: actions/checkout@v4
112+
- name: Pull Material for MKdocs image and build doc
113+
run: |
114+
docker pull squidfunk/mkdocs-material
115+
docker run --rm -i -v ${PWD}:/docs squidfunk/mkdocs-material build
116+
- name: Download and set up AWS CLI
117+
run: |
118+
sudo apt update
119+
sudo apt install curl unzip -y
120+
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64-2.22.20.zip" -o "awscliv2.zip"
121+
unzip awscliv2.zip
122+
sudo ./aws/install --update
123+
- name: Set up AWS credentials
124+
env:
125+
DOC_ACCESS_KEY: ${{ secrets.DOC_ACCESS_KEY }}
126+
DOC_SECRET_KEY: ${{ secrets.DOC_SECRET_KEY }}
127+
run: |
128+
aws configure set aws_access_key_id $DOC_ACCESS_KEY
129+
aws configure set aws_secret_access_key $DOC_SECRET_KEY
130+
aws configure set region fr-par
131+
- name: Upload file to Scaleway Object Storage
132+
env:
133+
DOC_BUCKET_NAME: ${{ secrets.DOC_BUCKET_NAME }}
134+
DOC_S3_ENDPOINT: ${{ secrets.DOC_S3_ENDPOINT }}
135+
run: |
136+
aws s3 cp --recursive ./site/ s3://$DOC_BUCKET_NAME --endpoint-url $DOC_S3_ENDPOINT
137+
```
138+
139+
## Adding your secrets in GitHub
140+
141+
In this section, we will be adding the following values (secrets) in our GitHub repository. This will allow the GitHub Actions workflow to access your bucket using the information in the `deploy-docs.yml` file.
142+
143+
- `DOC_ACCESS_KEY`: Your Scaleway API access key.
144+
- `DOC_SECRET_KEY`: Your Scaleway API secret key.
145+
- `DOC_BUCKET_NAME`: The name of your Scaleway bucket.
146+
- `DOC_S3_ENDPOINT`: The Scaleway endpoint of your bucket's region. For example, if your bucket is located in `FR-PAR`, the endpoint is `https://s3.fr-par.scw.cloud/`.
147+
148+
1. Access your GitHub repository.
149+
2. Click the **Settings** tab.
150+
3. Click the **Secrets and varaibles** section, then click **Actions**. You are redirected to the **Secrets** tab.
151+
4. Click **New repository secret**.
152+
5. Enter a name and a secret for each of the values listed above. For example, enter `DOC_ACCESS_KEY` in the **Name** field, and `SCWXXXXXXXXXXXXXXXXX` in the **Secret** field.
153+
6. Click **Add secret** and repeat the operation for the other 3 secrets.
154+
155+
## Deploying your documentation
156+
157+
1. Make sure that the **only action** in the statement to grant read access to your bucket is `s3:GetObject`. Your statement should look like the following:
158+
```
159+
{
160+
"Sid": "Grant read access to website",
161+
"Effect": "Allow",
162+
"Principal": "*",
163+
"Action": "s3:GetObject",
164+
"Resource": "name-of-your-bucket/*"
165+
},
166+
```
167+
2. Access your GitHub repository.
168+
3. Click the **Actions** tab. The name of your workflow (`Build and push website documentation to S3`) should display under **All workflows**.
169+
4. Click the name of your workflow, then click the **Run workflow** drop-down. You are prompted to select a branch from which to run the workflow.
170+
171+
| **Run workflow from `main` if** | **Run workflow from other branches if** |
172+
|---------------------------------------------------------------------|-------------------------------------------|
173+
| You want to deploy an official documentation to production. | You need to test documentation changes before merging. |
174+
| The documentation update is final and reviewed. | You are working on a feature, fix, or draft documentation update. |
175+
| The main branch is the source of truth for published documentation. | You want to generate a preview or staging deployment. |
176+
| The workflow is configured to push updates to a live website | The workflow includes validation checks like linting, broken link detection, or build testing. |
177+
| The changes need to be immediately available to users. | You are collaborating on documentation changes that require review before merging. |
178+
179+
5. Click **Run workflow**.
180+
181+
GitHub Actions will:
182+
183+
- build your MkDocs website,
184+
- push the content to your Scaleway Object Storage bucket, and
185+
- make your documentation accessible via the configured bucket URL.
186+
187+
## Going further
188+
189+
If you expect high traffic, consider using our [Edge Services](/edge-services/quickstart/) solution for caching.
190+
191+
If you have a custom domain, you can link it to your documentation website in your `mkdocs.yml` file.

0 commit comments

Comments
 (0)