Skip to content

Add mkdocs documentation build to playground deployment workflow #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Sander-Toonen merged 2 commits into from
Jan 23, 2026
Merged

Add mkdocs documentation build to playground deployment workflow #39

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5896600
Initial plan
Copilot Jan 23, 2026
db6cda8
Add mkdocs documentation build to deploy-playground workflow
Copilot Jan 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .github/workflows/deploy-playground.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,17 @@ jobs:
- name: Build UMD bundle
run: npm run build:umd

- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: '3.x'
Copy link

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding pip caching to improve build performance, similar to how npm is cached for Node.js. The setup-python action supports caching pip dependencies by adding a 'cache' parameter. This would speed up subsequent workflow runs by avoiding re-downloading mkdocs-material and its dependencies each time.

Suggested change
python-version: '3.x'
python-version: '3.x'
cache: 'pip'

Copilot uses AI. Check for mistakes.

- name: Install mkdocs
run: pip install mkdocs-material==9.7.1

Copy link

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation is being deployed to '/docs/' subdirectory, but the mkdocs.yml configuration has 'site_url: https://pro-fa.github.io/expr-eval/' (without '/docs/'). This mismatch may cause issues with internal links, asset paths, and sitemap generation in the built documentation. Consider either updating mkdocs.yml to set 'site_url: https://pro-fa.github.io/expr-eval/docs/' or using the 'use_directory_urls: false' option, or alternatively modifying this workflow step to update the site_url before building with a command like 'sed -i "s|site_url:.*|site_url: https://pro-fa.github.io/expr-eval/docs/|" mkdocs.yml' before running 'mkdocs build'.

Suggested change
- name: Update mkdocs site_url for /docs/ deployment
run: sed -i 's|^site_url:.*|site_url: https://pro-fa.github.io/expr-eval/docs/|' mkdocs.yml

Copilot uses AI. Check for mistakes.
- name: Build documentation
run: mkdocs build

- name: Prepare playground files
run: |
mkdir -p _site/dist
Expand All @@ -43,6 +54,7 @@ jobs:
cp samples/language-service-sample/examples.js _site/
cp samples/language-service-sample/styles.css _site/
cp dist/bundle.js _site/dist/
cp -r site _site/docs
Copy link

Copilot AI Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The 'site' directory is being copied without first verifying that the mkdocs build step successfully created it. If 'mkdocs build' fails or doesn't produce output, the copy command will fail with a potentially unclear error message. Consider adding a verification step or using a more defensive copy command like 'cp -r site _site/docs || echo "Warning: mkdocs site directory not found"' to make troubleshooting easier. Alternatively, ensure the mkdocs build command will fail the workflow if it encounters an error.

Suggested change
cp -r site _site/docs
if [ -d site ]; then
cp -r site _site/docs
else
echo "Warning: mkdocs 'site' directory not found; skipping docs copy"
fi

Copilot uses AI. Check for mistakes.

- name: Setup Pages
uses: actions/configure-pages@v5
Expand Down