Bugfix/home docs (#626)

Seburan · web-flow · commit 01d3479a4c6a · 2025-04-21T11:01:24.000+09:00
* demo docs fixes : - fix issue #624 - fix issue #623 - fix issue #622 - fix issue #621 Documentation Fixes: The PR resolves multiple documentation issues by fixing relative file paths and URLs in the markdown files. It also updates image links to use relative paths instead of absolute URLs. Docusaurus Configuration: The Docusaurus configuration is updated to throw an exception when Markdown links are broken, ensuring link integrity. The trailingSlash option is enabled to add trailing slashes to URLs. Nginx Configuration: The Nginx configuration is strengthened by upgrading Nginx to version 1.27.5-alpine and adding directives for security and optimization. The configuration file is now directly copied to /etc/nginx/nginx.conf instead of using a template. Docker Compose Update: The docker-compose.yml file is updated to use the newer Nginx image version 1.27.5-alpine. Markdown file paths are preferred. see https://docusaurus.io/docs/next/markdown-features/links updated docusaurus config to throw an exception when Markdown links are broken * [home] strenghten nginx configuration upgrade nginx add nginx.conf directives for security and optimization * fix docs link to full sized image hosted on Github
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -224,7 +224,7 @@ services:
       - adnetwork
 
   nginx:
-    image: nginx:1.22.1-alpine
+    image: nginx:1.27.5-alpine
     container_name: "proxy"
     volumes:
       # using env variables in nginx config
diff --git a/services/home/Dockerfile b/services/home/Dockerfile
@@ -12,9 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-FROM nginx:1.25-alpine3.17
+FROM nginx:1.27.5-alpine
 
-COPY --chown=nginx:nginx nginx.conf /etc/nginx/templates/default.conf.template
+# Copy custom Nginx configuration
+COPY --chown=nginx:nginx nginx.conf /etc/nginx/nginx.conf
+
+# Copy built Docusaurus site from the buid folder
 COPY --chown=nginx:nginx build /usr/share/nginx/html
 
+# Nginx listens on 8080, expose it (for documentation/clarity)
+EXPOSE 8080
+
+# Start Nginx in the foreground
 CMD [ "nginx", "-g", "daemon off;" ]
diff --git a/services/home/docs/demos/bidding-and-auction.md b/services/home/docs/demos/bidding-and-auction.md
@@ -85,12 +85,13 @@ components of the system work together to complete an auction.
 - The seller's real time bidding service then forwards the encrypted ad auction result back to the publisher page. Then the
   `navigator.runAdAuction()`function runs on the page and displays the winning ad.
 
-![Bidding Auction API Flow](https://raw.githubusercontent.com/privacysandbox/privacy-sandbox-demos/73a017521449a526da715aabeaa02734faead7b3/services/home/docs/demos/img/bidding-auction-api-flow.png)
+![Bidding Auction API Flow](img/bidding-auction-api-flow.png)
 
 #### User Journey
 
-```bash
+```mermaid
 sequenceDiagram
+
     Browser->>+Advertiser: User visits a shop site and clicks on a product
     DSP -->>DSP: DSP implements payload optimization
     DSP-->>Browser: DSP calls navigator.joinAdInterestGroup(...)
@@ -110,7 +111,7 @@ sequenceDiagram
     Publisher Page-->>Browser: Top level seller runs navigator.runAdAuction(auctionConfig) on-device
 ```
 
-#TODO: add valid permalink ![User Journey](../demos/img/bidding-and-auction-flow.png)
+[Full-sized diagram](https://github.com/privacysandbox/privacy-sandbox-demos/blob/ff68148e0987979ecdac2f0183b9ca2a1b847bcc/services/home/docs/demos/img/bidding-and-auction-flow.png)
 
 </TabItem>
 
@@ -632,7 +633,7 @@ sspYRouter.get('/construct-component-auction.js', async (req, res) => {
 ```
 
 7. The
-   [construct-component-auction.ts](https://github.com/privacysandbox/privacy-sandbox-demos/blob/dev/services/ad-tech/src/public/js/ssp/usecase/bidding-and-auction/ssp-y/construct-component-auction.ts#L35)
+   [construct-component-auction.ts](https://github.com/privacysandbox/privacy-sandbox-demos/blob/ff68148e0987979ecdac2f0183b9ca2a1b847bcc/services/ad-tech/src/public/js/ssp/usecase/bidding-and-auction/ssp-y/construct-component-auction.ts#L35)
    file will first build the auction config.
 
 ```typescript
@@ -755,10 +756,10 @@ async #runComponentAdAuction(request: number[]) {
     The selectAd request can also be sent with a REST API call. This
     [proto file](https://github.com/privacysandbox/privacy-sandbox-demos/blob/e9b604243b99c4629b78a578844d054770f9d660/services/ad-tech/src/routes/ssp/usecase/bidding-and-auction/server/proto/sfe-client.proto#L3)
     defines the interface for interacting with the seller frontend service. The `ciphertextShaHash` uses the response from the seller front end and
-    generates a SHA-256 hash with base64 encoding. This is to ensure payload security between the seller ad service and the browser.  
-    The ciphertext is then set as the value for the `Ad-Auction-Result` header to be passed back to the browser. The `onDeviceAuctionConfig` field is
-    set to define the auction configuration for the on-device component of mixed mode. This will be passed to the browser along with the bidding and
-    auction result, but it will appear as a separate component auction in the browser.
+    generates a SHA-256 hash with base64 encoding. This is to ensure payload security between the seller ad service and the browser. The ciphertext is
+    then set as the value for the `Ad-Auction-Result` header to be passed back to the browser. The `onDeviceAuctionConfig` field is set to define the
+    auction configuration for the on-device component of mixed mode. This will be passed to the browser along with the bidding and auction result, but
+    it will appear as a separate component auction in the browser.
 
 ```typescript
    mixedModeClientSFE.selectAd(
diff --git a/services/home/docs/demos/instream-video-ad.md b/services/home/docs/demos/instream-video-ad.md
@@ -21,10 +21,10 @@ this use case.
 
 ### Description
 
-This demo expands on the demo for the [sequential setup of Protected Audience with contextual auction](sequential-auction-setup) to showcase how video
-ads may be served with Protected Audience. The demo uses the industry-standard Video Ads Serving Template (VAST) XMLs to deliver video ads in iframes.
-Additionally, note that the technique shown in this demo does not work with [Fenced Frames](https://privacysandbox.google.com/relevance/fenced-frame),
-but Protected Audience allows iframe usage
+This demo expands on the demo for the [sequential setup of Protected Audience with contextual auction](sequential-auction-setup.md) to showcase how
+video ads may be served with Protected Audience. The demo uses the industry-standard Video Ads Serving Template (VAST) XMLs to deliver video ads in
+iframes. Additionally, note that the technique shown in this demo does not work with
+[Fenced Frames](https://privacysandbox.google.com/relevance/fenced-frame), but Protected Audience allows iframe usage
 [until at least 2026](https://privacysandbox.google.com/relevance/protected-audience-api/feature-status#fenced_frames).
 
 ### Privacy Sandbox APIs and related documentation
@@ -71,7 +71,7 @@ video ad bids generated are within the Protected Audience auction.
 
 ### System Design
 
-Identical to the [sequential auction setup demo](sequential-auction-setup), the user visiting an advertiser page is added to interest groups by
+Identical to the [sequential auction setup demo](sequential-auction-setup.md), the user visiting an advertiser page is added to interest groups by
 multiple DSPs. The auction orchestration on the news publisher page is also similar at a high-level. The incremental difference is in the post-auction
 rendering phase where the output of the Protected Audience auction needs to be consumed by a video player.
 
@@ -90,8 +90,8 @@ rendering phase where the output of the Protected Audience auction needs to be c
   post-messages it to the ad server library code on the publisher's page.
 - Finally, this ad server library passes the VAST XML to the video player
 
-Since the overall auction orchestration for this use-case identical to that in the [sequential auction setup demo](sequential-auction-setup), we will
-skip ahead to the ad rendering phase.
+Since the overall auction orchestration for this use-case identical to that in the [sequential auction setup demo](sequential-auction-setup.md), we
+will skip ahead to the ad rendering phase.
 
 ```mermaid
 sequenceDiagram
@@ -148,7 +148,7 @@ Browsr ->> Browser: Ad server library passes this finalized VAST to the video pl
 ### Implementation Details
 
 The user is added to interest groups by ad buyers or DSPs using the same high-level flow as described in the
-[basic remarketing / retargeting use-case demo](retargeting-remarketing). These interest groups contain both display and video ads, with the DSPs
+[basic remarketing / retargeting use-case demo](retargeting-remarketing.md). These interest groups contain both display and video ads, with the DSPs
 filtering for the ad type corresponding to that signalled by ad sellers or SSPs via `auctionSignals`.
 
 #### How is the video ad structured as an interest group ad?
@@ -213,7 +213,7 @@ const interestGroup = {
 
 SSPs indicate the supported ad type in `auctionConfig.auctionSignals` which is made available to the DSP's `generateBid()` method at auction time.
 Using this information, DSPs can filter for the appropriate ad types in their
-[bidding logic :arrow_upper_right:](https://github.com/privacysandbox/privacy-sandbox-demos/blob/dev/services/ad-tech/src/public/js/dsp/default/auction-bidding-logic.js#L261-264);
+[bidding logic :arrow_upper_right:](https://github.com/privacysandbox/privacy-sandbox-demos/blob/ff68148e0987979ecdac2f0183b9ca2a1b847bcc/services/ad-tech/src/public/js/dsp/usecase/default/auction-bidding-logic.js#L261-264);
 
 #### What does the interest group ad creative do?
 
@@ -232,11 +232,11 @@ includes a single
 wrapping the VAST XML.
 
 This script starts by
-[parsing :arrow_upper_right:](https://github.com/privacysandbox/privacy-sandbox-demos/blob/67d4c6368ff422ad9e952961352b5ac74ee9f500/services/ad-tech/src/public/js/video-ad-frame.js#L38-48)
+[parsing :arrow_upper_right:](https://github.com/privacysandbox/privacy-sandbox-demos/blob/ff68148e0987979ecdac2f0183b9ca2a1b847bcc/services/ad-tech/src/public/js/video-ads.js#L38)
 the SSP's VAST wrapping endpoint including in the URL. Then the scripts proceeds to
-[fetch the finalized VAST XML from this SSP endpoint :arrow_upper_right:](https://github.com/privacysandbox/privacy-sandbox-demos/blob/67d4c6368ff422ad9e952961352b5ac74ee9f500/services/ad-tech/src/public/js/video-ad-frame.js#L51-69)
+[fetch the finalized VAST XML from this SSP endpoint :arrow_upper_right:](https://github.com/privacysandbox/privacy-sandbox-demos/blob/ff68148e0987979ecdac2f0183b9ca2a1b847bcc/services/ad-tech/src/public/js/video-ads.js#L51)
 before
-[post-messaging the XML content to the top frame :arrow_upper_right:](https://github.com/privacysandbox/privacy-sandbox-demos/blob/dev/services/ad-tech/src/public/js/video-ad-frame.js#L107-115).
+[post-messaging the XML content to the top frame :arrow_upper_right:](https://github.com/privacysandbox/privacy-sandbox-demos/blob/ff68148e0987979ecdac2f0183b9ca2a1b847bcc/services/ad-tech/src/public/js/video-ads.js#L108).
 
 ```js title="Winning PA ad iframe assembles and post-messages the finalized VAST to the top frame"
 // ...
diff --git a/services/home/docs/demos/multi-piece-ad.md b/services/home/docs/demos/multi-piece-ad.md
@@ -36,8 +36,8 @@ through a template 'container' with customizable product slots.
 ### Goals
 
 In this demo, the auction setup and execution is similar to the
-[sequential setup of Protected Audience with contextual ad auction](https://privacy-sandbox-demos.dev/docs/demos/sequential-auction-setup/) demo. So,
-please check this use case implementation first if you want to learn about the Protected Audience auction setup.
+[sequential setup of Protected Audience with contextual ad auction](./sequential-auction-setup.md) demo. So, please check this use case implementation
+first if you want to learn about the Protected Audience auction setup.
 
 The only incremental difference in this use-case is that the advertiser can provide more than one product that the user interacted with in the same ad
 slot.
diff --git a/services/home/docs/demos/publisher-ad-quality-req.md b/services/home/docs/demos/publisher-ad-quality-req.md
@@ -125,7 +125,7 @@ Browser ->> DSP: Request ad creative
 DSP -->> Browser: Return ad creative
 ```
 
-[Full-sized diagram](./img/publisher-ad-quality-req-flow.png)
+[Full-sized diagram](https://github.com/privacysandbox/privacy-sandbox-demos/blob/ff68148e0987979ecdac2f0183b9ca2a1b847bcc/services/home/docs/demos/img/publisher-ad-quality-req-flow.png)
 
 </TabItem>
 <TabItem value="demo" label="Demo">
@@ -166,9 +166,9 @@ shoe ad from Protected Audience will not be delivered. Instead, the ad from the
 ### Implementation details
 
 To add the user to an interest group, we reuse the implementation from the
-[basic retargeting / remarketing ad campaign use-case demo](retargeting-remarketing). It’s in the second half -- the auction execution and ad delivery
--- where this use case differs from the regular retargeting / remarketing use-case. This is also why this use-case is on a different page on the news
-site.
+[basic retargeting / remarketing ad campaign use-case demo](retargeting-remarketing.md). It’s in the second half -- the auction execution and ad
+delivery -- where this use case differs from the regular retargeting / remarketing use-case. This is also why this use-case is on a different page on
+the news site.
 
 The news page lists the available ad slot on the page in the
 [`window.PSDemo.PAGE_ADS_CONFIG`](https://github.com/privacysandbox/privacy-sandbox-demos/blob/67d4c6368ff422ad9e952961352b5ac74ee9f500/services/news/src/views/publisher-ad-quality-req.ejs#L29)
@@ -198,7 +198,7 @@ window.PSDemo.PAGE_ADS_CONFIG = Object.freeze({
 To deliver an ad for this ad slot, the news page also includes a third-party tag:
 [ad-server-tag.js](https://github.com/privacysandbox/privacy-sandbox-demos/blob/67d4c6368ff422ad9e952961352b5ac74ee9f500/services/news/src/views/publisher-ad-quality-req.ejs#L43)
 from the ad-server service. This ad server tag reads the ad slot configurations and proceeds to execute a sequential contextual + Protected Audience
-auction as described in the [sequential setup of Protected Audience with contextual ad auction demo](sequential-auction-setup).
+auction as described in the [sequential setup of Protected Audience with contextual ad auction demo](sequential-auction-setup.md).
 
 ```html title="Ad-server tag on publisher page: https://privacy-sandbox-demos-news.dev"
 <script
diff --git a/services/home/docs/demos/sequential-auction-setup.md b/services/home/docs/demos/sequential-auction-setup.md
@@ -45,7 +45,7 @@ Audience as an additional demand source that may or may not beat the contextual
 
 In this demo, we aim to demonstrate a basic sequential auction setup with a focus on the data flow from the perspective of the Protected Audience
 auction and abstract a lot of the technical nuance in the contextual auction. Building on the
-[basic retargeting / remarketing ads demo](retargeting-remarketing), this demo shows a more realistic sequential setup with multiple buyers and
+[basic retargeting / remarketing ads demo](retargeting-remarketing.md), this demo shows a more realistic sequential setup with multiple buyers and
 sellers participating in the ad delivery process. This demo will also demonstrate SSPs sourcing `buyerSignals` from DSPs and including them in the
 Protected Audience auction configuration.
 
@@ -57,8 +57,8 @@ various ad delivery setups. This demo focuses on a few exemplary _'signals'_ as
 
 ### System Design
 
-Identical to the [basic retargeting / remarketing ads demo](retargeting-remarketing), the user visiting an advertiser page is added to interest groups
-by multiple DSPs. While the overall ad delvery flow on the publisher page is similar, the biggest difference in this demo is the involvement of
+Identical to the [basic retargeting / remarketing ads demo](retargeting-remarketing.md), the user visiting an advertiser page is added to interest
+groups by multiple DSPs. While the overall ad delvery flow on the publisher page is similar, the biggest difference in this demo is the involvement of
 multiple ad sellers. The publisher ad server starts with a simplified contextual auction with other sellers also participating to arrive at a winning
 contextual ad while also collating their auction configurations for the Protected Audience auction. The publisher ad server also initiates the
 Protected Audience auction acting as the top-level seller with all sellers including the publisher ad server conducting their individual component
@@ -173,7 +173,7 @@ end
 ### Implementation details
 
 The user is added to interest groups by DSPs using the same mechanism as described in the
-[basic remarketing / retargeting use-case demo](retargeting-remarketing). The incremental difference in the implementation of this demo is on the
+[basic remarketing / retargeting use-case demo](retargeting-remarketing.md). The incremental difference in the implementation of this demo is on the
 publisher page.
 
 #### How does the publisher pass the ad unit configurations for a given page to the publisher ad server?
@@ -237,7 +237,7 @@ More specifically, the `ad-server-tag.js` injects an iframe for each ad unit whe
 Protected Audience auction to choose an ad. This iframe loads:
 [`https://privacy-sandbox-demos-ad-server.dev/ssp/run-sequential-ad-auction.html` :arrow_upper_right:](https://github.com/privacysandbox/privacy-sandbox-demos/blob/67d4c6368ff422ad9e952961352b5ac74ee9f500/services/ad-tech/src/views/ssp/run-sequential-ad-auction.ejs),
 which contains a single script:
-[`https://privacy-sandbox-demos-ad-server.dev/js/ssp/run-sequential-ad-auction.js` :arrow_upper_right:](https://github.com/privacysandbox/privacy-sandbox-demos/blob/dev/services/ad-tech/src/public/js/ssp/run-sequential-ad-auction.js).
+[`https://privacy-sandbox-demos-ad-server.dev/js/ssp/run-sequential-ad-auction.js` :arrow_upper_right:](https://github.com/privacysandbox/privacy-sandbox-demos/blob/ff68148e0987979ecdac2f0183b9ca2a1b847bcc/services/ad-tech/src/public/js/ssp/run-sequential-ad-auction.js).
 This iframe expects a post-message from `ad-server-tag.js` containing the ad unit configuration as well as the list of other sellers involved in the
 ad delivery process.
 
@@ -341,7 +341,7 @@ SellerContextualBidderRouter.get('/', async (req: Request, res: Response) => {
 
 The publisher ad servers collates the contextual bid responses from all the sellers before assembling the combined auction configuration for Protected
 Audience. In the following code snippet from
-[`run-sequential-ad-auction.js` :arrow_upper_right:](https://github.com/privacysandbox/privacy-sandbox-demos/blob/dev/services/ad-tech/src/public/js/ssp/run-sequential-ad-auction.js#L145-182),
+[`run-sequential-ad-auction.js` :arrow_upper_right:](https://github.com/privacysandbox/privacy-sandbox-demos/blob/ff68148e0987979ecdac2f0183b9ca2a1b847bcc/services/ad-tech/src/public/js/ssp/run-sequential-ad-auction.js#L154),
 the winning contextual bid is chosen purely on the bid price. Along with the contextual bid response, the additional sellers or SSPs also respond with
 their Protected Audience component auction configuration. The publisher ad server also assembles the final Protected Audience auction configuration
 which includes these component auction configurations from other sellers as well as its own component auction.
diff --git a/services/home/docs/intro.md b/services/home/docs/intro.md
@@ -18,10 +18,10 @@ Looking to run these demos yourself? Check our [guide](https://github.com/privac
 | [Incorporating publisher ad quality requirements in Protected Audience](demos/publisher-ad-quality-req.md) | Protected Audience, Fenced Frames                        |
 | [In-stream video ads with Protected Audience](demos/instream-video-ad.md)                                  | Protected Audience                                       |
 | [Ads Composed of Multiple Pieces](demos/multi-piece-ad.md)                                                 | Protected Audience                                       |
-| [Bidding & Auction Services for Protected Audience](demos/bidding-and-auction)                             | Protected Audience, Bidding & Auction Services           |
+| [Bidding & Auction Services for Protected Audience](demos/bidding-and-auction.md)                          | Protected Audience, Bidding & Auction Services           |
 | [Event-level reports for single touch attribution](demos/single-touch-event-level-report.md)               | Attribution Reporting                                    |
 | [Reach Measurement](demos/reach-measurement-with-shared-storage.md)                                        | Shared Storage, Private Aggregation                      |
-| [Multi-touch conversion Attribution](demos/multi-touch-conversion-attribution)                             | Private Aggregation, Shared Storage, Aggregation Service |
+| [Multi-touch conversion Attribution](demos/multi-touch-conversion-attribution.md)                          | Private Aggregation, Shared Storage, Aggregation Service |
 | [Single-touch conversion attribution](demos/single-touch-conversion-attribution.md)                        | Protected Audience, Fenced Frames, Attribution Reporting |
 
 :::info
diff --git a/services/home/docusaurus.config.js b/services/home/docusaurus.config.js
@@ -20,13 +20,16 @@ const config = {
   // For GitHub pages deployment, it is often '/<projectName>/'
   baseUrl: '/',
 
+  // true: add trailing slashes to URLs/links, and emit /docs/myDoc/index.html for /docs/myDoc.md
+  trailingSlash: true,
+
   // GitHub pages deployment config.
   // If you aren't using GitHub pages, you don't need these.
   organizationName: 'privacysandbox/privacy-sandbox-demos', // Usually your GitHub org/user name.
   projectName: 'privacy-sandbox-demos', // Usually your repo name.
 
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
+  onBrokenMarkdownLinks: 'throw',
 
   // Even if you don't use internalization, you can use this field to set useful
   // metadata like html lang. For example, if your site is Chinese, you may want
diff --git a/services/home/nginx.conf b/services/home/nginx.conf
