datacommonsorg · juliawu · Mar 11, 2026 · Feb 27, 2026 · Feb 27, 2026 · Mar 10, 2026
diff --git a/_config.yml b/_config.yml
@@ -47,5 +47,6 @@ exclude:
   - vendor/gems/
   - vendor/ruby/
   - STYLE_GUIDE.md
+  - "**/README.md"
 
 include: ["CNAME"]
diff --git a/_layouts/code-preview.html b/_layouts/code-preview.html
@@ -0,0 +1,83 @@
+{% comment %}
+Displays another page inside an iframe with source code on the left and the page on the right
+
+For maintainers: Set the url to display using the iframe_content_url variable in the frontmatter. 
+{% endcomment %}
+
+<!doctype html>
+
+<html lang="en">
+  <head>
+    <title>{{ page.title | escape }} - Docs - Data Commons</title>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1, shrink-to-fit=no"
+    />
+    <link rel="icon" href="/assets/images/favicon.png" type="image/png" />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Google+Sans:wght@300;400;500;700"
+      rel="stylesheet"
+    />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Google+Sans+Text:wght@300;400;500;700"
+      rel="stylesheet"
+    />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Public+Sans:wght@600&family=Roboto&family=Material+Icons&display=swap"
+      rel="stylesheet"
+    />
+    <link href="/assets/css/styles.css" rel="stylesheet" />
+    <link href="/assets/css/code-preview.css" rel="stylesheet" />
+    <!-- Syntax highlighting for code -->
+    <link
+      rel="stylesheet"
+      href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism.min.css"
+    />
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script>
+  </head>
+  <body>
+    <div id="main">
+      {% include header.html %}
+      <main id="{{ main_id }}" class="container-fluid">
+        <div id="content">
+          <div id="source-code">
+            <h3>Source Code</h3>
+            <pre><code id="code-target" class="language-html">Loading source code...</code></pre>
+          </div>
+          <div id="preview">
+            <h3>Output</h3>
+            <iframe
+              id="iframe"
+              title="{{ page.title | escape }} Rendered Output"
+              src="{{ page.iframe_content_url | escape}}"
+              sandbox="allow-scripts allow-popups"
+            ></iframe>
+          </div>
+        </div>
+      </main>
+      {% include footer.html %}
+    </div>
+    <script>
+      // Fetch the source code for the page and display it in the source code
+      // div.
+      const fileUrl = "{{ page.iframe_content_url | escape }}";
+      fetch(fileUrl)
+        .then((response) => {
+          if (!response.ok) throw new Error("Network response was not ok");
+          return response.text();
+        })
+        .then((data) => {
+          // Escape the HTML so it doesn't render as actual elements
+          const codeTarget = document.getElementById("code-target");
+          codeTarget.textContent = data;
+          Prism.highlightElement(codeTarget);
+        })
+        .catch((err) => {
+          document.getElementById("code-target").textContent =
+            "Error loading source: " + err.message;
+        });
+    </script>
+    {% include scripts.html %}
+  </body>
+</html>
diff --git a/api/web_components/examples/README.md b/api/web_components/examples/README.md
@@ -0,0 +1,31 @@
+# Web Components Examples
+
+This directory contains the pages that render the side-by-side source code and rendered output for the Data Commons web components examples.
+
+## How the examples are rendered
+
+The examples are rendered into the `code-preview` layout in `/_layouts/code-preview.html`.
+
+A `<script>` tag in the layout pulls the the raw HTML source of the file specified in the `iframe_content_url` frontmatter property and displays it in a `<code>` block. It then applies syntax highlighting to the code via [Prism.js](https://prismjs.com/).
+
+The right-side live-render is an iframe that loads the same file.
+
+## How to add a new example
+
+1. Add a new HTML file to the assets/examples/web-components/ directory containing the full HTML for the example.
+2. Create a new markdown file in this directory that uses the code-preview layout.
+3. Add frontmatter to the new file following this template:
+
+```yaml
+---
+layout: code-preview
+title: Web components example - [SOME DESCRIPTIVE NAME HERE]
+published: true
+nav_exclude: true # This keeps the page from showing up in the left navigation
+iframe_content_url: /assets/examples/web-components/[FILENAME].html
+---
+```
+
+The `iframe_content_url` should point to the HTML file you created in step 1.
+
+4. Finally, you can link to the new example using the path `/api/web_components/examples/[FILENAME].html`
diff --git a/api/web_components/examples/all-charts.md b/api/web_components/examples/all-charts.md
@@ -0,0 +1,8 @@
+---
+layout: code-preview
+title: All Charts
+parent: All Charts - Web Components Example
+published: true
+nav_exclude: true
+iframe_content_url: /assets/examples/web-components/all-charts.html
+---
diff --git a/assets/css/code-preview.scss b/assets/css/code-preview.scss
@@ -0,0 +1,111 @@
+---
+---
+
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * CSS for the code-preview layout (e.g., /api/web_components/examples/all-charts.html)
+ */
+
+html,
+body {
+  height: 100vh;
+}
+
+#main {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+
+  > main {
+    flex-grow: 1;
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    padding: 0;
+  }
+}
+
+header,
+footer {
+  flex-shrink: 0;
+}
+
+#content {
+  flex-grow: 1;
+  margin: 0;
+  min-height: 0;
+  display: flex;
+  overflow: hidden;
+
+  /* On smaller screens, show source code and preview top to bottom */
+  @media (max-width: 1024px) {
+    flex-direction: column;
+  }
+}
+
+#preview,
+#source-code {
+  width: 50%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+
+  h3 {
+    margin: 0;
+    padding: 10px;
+    background: #fafcff;
+    border-top: 1px solid #dee2e6;
+    border-bottom: 1px solid #dee2e6;
+    flex-shrink: 0;
+    font-size: 1rem;
+    font-weight: 500;
+  }
+
+  /* On smaller screens, show source code and preview top to bottom */
+  @media (max-width: 1024px) {
+    width: 100%;
+    height: 50%;
+    min-height: 0;
+  }
+}
+
+#preview {
+  iframe {
+    border: none;
+    width: 100%;
+    flex-grow: 1;
+    min-height: 0;
+  }
+}
+
+#source-code {
+  pre {
+    margin: 0;
+    flex-grow: 1;
+    overflow: auto;
+    min-height: 0;
+    padding: 10px;
+  }
+}
+
+#code-target {
+  /* Reset specific height/overflow as pre handles it now */
+  height: auto;
+  overflow: visible;
+}
diff --git a/assets/examples/web-components/all-charts.html b/assets/examples/web-components/all-charts.html
@@ -18,14 +18,15 @@
         stroke-dasharray: unset;
       }
       #styled-bar-multivariable::part(
-          series-place-geoId\/20-variable-Median_Income_Person_15OrMoreYears_Male_WithIncome
-        ) {
+        series-place-geoId\/20-variable-Median_Income_Person_15OrMoreYears_Male_WithIncome
+      ) {
         fill: green;
       }
       #styled-map::part(container) {
         border-radius: 10px;
         border: 1px solid #f5f5f5;
-        box-shadow: 1px 2px 6px rgba(3, 7, 18, 0.04),
+        box-shadow:
+          1px 2px 6px rgba(3, 7, 18, 0.04),
           5px 8px 25px rgba(3, 7, 18, 0.08);
       }
       #styled-map::part(legend) {
@@ -71,7 +72,16 @@
       }
     </style>
   </head>
-  <body style="max-width: 40vw; margin: auto">
+  <body
+    style="
+      box-sizing: border-box;
+      max-width: 900px;
+      width: 100%;
+      overflow-x: hidden;
+      padding: 0 64px;
+      margin: 0 auto;
+    "
+  >
     <h1>Datacommons Web Components</h1>
     <h2>Bar Chart</h2>
     <datacommons-bar
@@ -333,15 +343,16 @@ <h2>Map with year slider</h2>
       header="Poverty rate by country (${date})"
       parentPlace="Earth"
       subscribe="dc-map-2"
-      variable="sdg/SI_POV_DAY1">
+      variable="sdg/SI_POV_DAY1"
+    >
       <div slot="footer">
         <datacommons-slider
           childPlaceType="Country"
           date="HIGHEST_COVERAGE"
           parentPlace="Earth"
           publish="dc-map-2"
           variable="sdg/SI_POV_DAY1"
-          >
+        >
         </datacommons-slider>
       </div>
     </datacommons-map>