Skip to content

Commit af62b3f

Browse files
simonkurtz-MSFTsimonkurtz-MSFT
authored
Add APIM Samples Website (#172)
1 parent 8619103 commit af62b3f

20 files changed

Lines changed: 2140 additions & 1 deletion

‎.github/copilot-instructions.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,7 @@ Uniformity, clarity, and ease of use are paramount across all infrastructures an
8282
- `/`: Root directory containing the main files and folders. Bicep configuration is stored in `bicepconfig.json`.
8383
- The following folders are all at the root level:
8484
- `assets/`: Draw.io diagrams, SVG exports, and images. Static assets such as these should be placed here. Architecture diagrams should be placed in the /diagrams subfolder.
85+
- `docs/`: Source for the public GitHub Pages landing page. See the *GitHub Pages Site* section below for upkeep rules.
8586
- `infrastructure/`: Contains Jupyter notebooks for setting up various API Management infrastructures. When modifying samples, these notebooks should not need to be modified.
8687
- `samples/`: Various policy and scenario samples that can be applied to the infrastructures.
8788
- `setup/`: General setup scripts and configurations for the repository and dev environment setup.
@@ -371,10 +372,27 @@ Match the heading emojis, heading levels, and section ordering exactly. If a sec
371372
- Document expected behavior for edge cases and error handling.
372373
- Write unit tests for functions and classes, following language-specific testing frameworks.
373374

375+
## GitHub Pages Site
376+
377+
The public landing page at <https://azure-samples.github.io/Apim-Samples/> is built from `docs/index.html` by `.github/workflows/github-pages.yml` on every push to `main`. The page intentionally mirrors a subset of the root `README.md` (infrastructure cards, sample cards, quick-start steps) so that visitors get a polished overview without cloning the repo.
378+
379+
**Treat `docs/index.html` as a downstream consumer of the README.** When you change any of the following, update the landing page in the same PR:
380+
381+
| Change | Update required in `docs/index.html` | Also update |
382+
|---|---|---|
383+
| Add / remove / rename an **infrastructure** | Add / remove / rename the matching `.infra-card` **and** the matching `ListItem` in the JSON-LD `ItemList` (in `<head>`). Update the infrastructure count in the first `.value-card` if it still says "Five". | Add / remove the SVG copy line in `.github/workflows/github-pages.yml`. |
384+
| Add / remove / rename a **sample** | Add / remove / rename the matching `.sample-card` **and** the matching `ListItem` in the JSON-LD `ItemList`. | — |
385+
| Change a sample's **supported infrastructures** | Update the `.infra-tag` text on that sample's card. | — |
386+
| Change the **quick-start flow** in the root README | Update the four `.step` items. | — |
387+
| Rename or replace an **architecture SVG** in `assets/diagrams/` | — | Update the matching `cp` line in `.github/workflows/github-pages.yml`. |
388+
389+
Check `docs/README.md` for local preview instructions and styling notes. The page is deliberately plain static HTML + an external stylesheet (`docs/styles.css`), with no executable JavaScript and no build tooling, so that it cannot rot due to a transitive npm dependency. The only `<script>` tag is the JSON-LD structured-data block, which must stay inline because search-engine crawlers do not reliably follow external JSON-LD references. Keep it that way unless there is a compelling reason to add a build step.
390+
374391
## Required before each commit
375392
- Ensure all code is well-documented and follows the guidelines in this file.
376393
- Ensure that Jupyter notebooks do not contain any cell output.
377394
- Ensure that Jupyter notebooks have `index` assigned to `1` in the first cell.
395+
- If the change touches the infrastructure list, sample list, quick-start steps, or architecture SVGs, ensure `docs/index.html` (and the asset copy step in `.github/workflows/github-pages.yml` where relevant) has been updated to match.
378396

379397
## Jupyter Notebook Instructions
380398

‎.github/workflows/github-pages.yml‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
name: GitHub Pages
2+
3+
# Publishes the static landing page at https://azure-samples.github.io/Apim-Samples/
4+
# The site source lives in /docs and pulls images from /assets at build time.
5+
# See docs/README.md for local preview instructions and the upkeep checklist.
6+
7+
on:
8+
workflow_dispatch:
9+
push:
10+
branches: [ main ]
11+
paths:
12+
# Only rebuild when something that actually lands on the page changes.
13+
- 'docs/**'
14+
- 'assets/APIM-Samples.png'
15+
- 'assets/APIM-Samples-Slide-Deck.html'
16+
- 'assets/favicon-*.png'
17+
- 'assets/apple-touch-icon.png'
18+
- 'assets/android-chrome-*.png'
19+
- 'assets/site.webmanifest'
20+
- 'assets/diagrams/*.svg'
21+
- 'setup/export_presentation.py'
22+
- '.github/workflows/github-pages.yml'
23+
24+
# Top-level default is read-only. The deploy job elevates only what GitHub
25+
# Pages needs (pages:write + id-token:write for the OIDC deploy token).
26+
permissions:
27+
contents: read
28+
29+
# Only one Pages deployment at a time. Newer pushes supersede in-flight ones,
30+
# but do not cancel a deploy that is already rolling out.
31+
concurrency:
32+
group: github-pages
33+
cancel-in-progress: false
34+
35+
jobs:
36+
build:
37+
name: Build site
38+
runs-on: ubuntu-latest
39+
steps:
40+
- name: Checkout code
41+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
42+
with:
43+
persist-credentials: false
44+
45+
- name: Configure Pages
46+
uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5.0.0
47+
48+
# Build the self-contained slide deck (all images inlined) so it can be
49+
# served as a single file at /slide-deck.html. The export script is
50+
# stdlib-only, so the runner's pre-installed Python is sufficient.
51+
- name: Export self-contained slide deck
52+
run: python3 setup/export_presentation.py
53+
54+
# The HTML references images at ./assets/... — stage them next to
55+
# index.html so the uploaded artifact is entirely self-contained.
56+
# Diagram SVGs are renamed to short, URL-safe slugs in the process.
57+
- name: Stage site artifact
58+
run: |
59+
set -euo pipefail
60+
61+
mkdir -p _site/assets/diagrams
62+
63+
cp docs/index.html _site/index.html
64+
cp docs/styles.css _site/styles.css
65+
cp docs/robots.txt _site/robots.txt
66+
cp docs/sitemap.xml _site/sitemap.xml
67+
68+
# Self-contained slide deck (built by the previous step)
69+
cp build/APIM-Samples-Slide-Deck.html _site/slide-deck.html
70+
71+
# Brand assets
72+
cp assets/APIM-Samples.png _site/assets/apim-samples-logo.png
73+
74+
# Favicon set + web app manifest. All six land flat in _site/assets/
75+
# because site.webmanifest resolves its icon src paths relative to
76+
# the manifest URL, not the page -- the android-chrome PNGs must be
77+
# siblings of the manifest file.
78+
cp assets/apple-touch-icon.png _site/assets/apple-touch-icon.png
79+
cp assets/favicon-32x32.png _site/assets/favicon-32x32.png
80+
cp assets/favicon-16x16.png _site/assets/favicon-16x16.png
81+
cp assets/site.webmanifest _site/assets/site.webmanifest
82+
cp assets/android-chrome-192x192.png _site/assets/android-chrome-192x192.png
83+
cp assets/android-chrome-512x512.png _site/assets/android-chrome-512x512.png
84+
85+
# Architecture diagrams (slugified -> matches <img src> in index.html)
86+
cp "assets/diagrams/Simple API Management Architecture.svg" \
87+
_site/assets/diagrams/simple-apim.svg
88+
cp "assets/diagrams/API Management & Container Apps Architecture.svg" \
89+
_site/assets/diagrams/apim-aca.svg
90+
cp "assets/diagrams/Azure Front Door, API Management & Container Apps Architecture.svg" \
91+
_site/assets/diagrams/afd-apim-pe.svg
92+
cp "assets/diagrams/Azure Application Gateway, API Management & Container Apps Architecture.svg" \
93+
_site/assets/diagrams/appgw-apim-pe.svg
94+
cp "assets/diagrams/Azure Application Gateway, API Management & Container Apps Architecture VNet.svg" \
95+
_site/assets/diagrams/appgw-apim.svg
96+
97+
# github.io does not need Jekyll processing for a plain HTML site.
98+
touch _site/.nojekyll
99+
100+
echo "Staged artifact contents:"
101+
find _site -type f -printf ' %p\n'
102+
103+
- name: Upload Pages artifact
104+
uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4.0.0
105+
with:
106+
path: _site
107+
108+
deploy:
109+
name: Deploy site
110+
needs: build
111+
runs-on: ubuntu-latest
112+
permissions:
113+
pages: write # to push to the Pages deployment
114+
id-token: write # to mint the OIDC token actions/deploy-pages needs
115+
environment:
116+
name: github-pages
117+
url: ${{ steps.deployment.outputs.page_url }}
118+
steps:
119+
- name: Deploy to GitHub Pages
120+
id: deployment
121+
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ labs-in-progress/
2121

2222
# Build exports
2323
/build/
24+
/_site/
2425

2526
# Misc
2627
*.log

‎assets/APIM-Samples-Slide-Deck.html‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,13 @@
2020
<meta name="release-approved" content="true" />
2121
<meta name="approval-date" content="2026-02-26" />
2222
<title>Azure API Management Samples - Presentation</title>
23-
<link rel="icon" type="image/png" href="favicon.png" />
23+
<!-- Favicon set. On the published site the exported deck lands at
24+
_site/slide-deck.html (same directory level as index.html), so the
25+
same ./assets/... paths resolve correctly. -->
26+
<link rel="apple-touch-icon" sizes="180x180" href="./assets/apple-touch-icon.png" />
27+
<link rel="icon" type="image/png" sizes="32x32" href="./assets/favicon-32x32.png" />
28+
<link rel="icon" type="image/png" sizes="16x16" href="./assets/favicon-16x16.png" />
29+
<link rel="manifest" href="./assets/site.webmanifest" />
2430
<style>
2531
* { margin: 0; padding: 0; box-sizing: border-box; }
2632

‎assets/android-chrome-192x192.png‎

53.5 KB
Loading

‎assets/android-chrome-512x512.png‎

253 KB
Loading

‎assets/apple-touch-icon.png‎

47.7 KB
Loading

‎assets/favicon-16x16.png‎

894 Bytes
Loading

‎assets/favicon-32x32.png‎

2.57 KB
Loading

‎assets/favicon.ico‎

14.3 KB
Binary file not shown.

0 commit comments

Comments
 (0)