feat: allow serving documentation site on a subpath #173

fvsch · 2023-10-30T19:08:19Z

This PR fixes issues with our documentation theme and config so that we can build the docs site and serve it as a subfolder of another website (for example on a /docs/ subpath).

VitePress has a built-in feature for this: the base option. That option handles a few things for us:

The base URL is prepended to menu and sidebar links, so a sidebar link's URLs can be defined as /guides/integration/open-from-github and will get completed to /docs/guides/integration/open-from-github (when base: '/docs/').
URLs in Markdown are also handled automatically, so a link like [some page](/guides/integration/open-from-github) will get a correct link.
Frontend assets handled by Vite will work out of the box.

We're still running into a few issues because we have some hardcoded URLs in our styles and Vue components.

Fixing URLs in components

We can use the withBase utility function provided by VitePress:

<a :href="withBase(url)">…</a>

This works well when the url value is either:

an absolute path starting with /, such as '/guides/integration/open-from-github';
an absolute URL with its own protocol and origin, such as 'https://stackblitz.com/enterprise' (in that case the URL is not modified by withBase).

Fixing links to assets (icons, images, fonts)

We were using hardcoded URLs to assets, oftentimes in CSS:

@font-face {
  /* … */
  src: url('/fonts/gilroy-medium.woff2') format('woff2');
}

This was linking absolutely to files placed in docs/public, which is a folder whose content gets copied as-is to the output folder (see related Vite docs).

If we want to serve the docs pages from a subpath, we would have to change those hardcoded paths to something else, for instance url('/docs/fonts/gilroy-medium.woff2').

Here the simpler solution is to have those assets be included in Vite's assets graph, by using relative imports to the asset, or the @theme/… import alias:

@font-face {
  /* … */
  /* fonts were moved to .vitepress/theme/fonts */
  src: url('@theme/fonts/gilroy-medium.woff2') format('woff2');
}

For images, including a few PNG backgrounds and a few SVG icons, I did something similar, and moved those files to:

.vitepress/
  theme/
    icons/
    img/

And referenced them in CSS as:

.card {
  background-image: url('@theme/img/link-bg-squares-dark.png');
}

or imported them in TypeScript or Vue components:

import bgDarkUrl from '@theme/img/link-bg-squares-dark.png';

The `<SvgIcon />` component

One special case for assets loading was some icons served from /img/icons/some-icon.svg, and used in CSS as CSS Masks:

.icon {
  display: inline-block;
  width: 1em;
  height: 1em;
  background-color: currentColor;
  mask: url('/img/icons/some-icon.svg');
}

This pattern was used in a handful of places, often reusing the same handful of icons.

I created a new SvgIcon component to replace this duplicated usage, and made it accept a string that matches the file name (without extension) of a file in .vitepress/theme/fonts/*.svg.

We first import all icons (which is reasonable because we have a manually curated icon set):

const importedIconsUrls = import.meta.glob('./*.svg', {
  as: 'url',
  eager: true,
});

Which gives us an object that looks like a manifest of icon URLs:

{
  './fa-books-light.svg': '/assets/fa-books-light.1221b65c.svg',
  './fa-brackets-curly.svg': '/assets/fa-brackets-curly.3f29fd46.svg',
  // …
}

Thanks to that, we can call <SvgIcon icon="fa-brackets-curly" /> and the SvgIcon component will look up the image URL in that object.

If we don't love this implementation, we can change it to have the consumer of SvgIcon pass a full URL:

<script setup>
import SvgIcon from '@theme/components/Icons/SvgIcon.vue';
import thumbsUpIcon from '@theme/icons/fa-thumbs-up.svg';
</script>

<template>
  <SvgIcon :url={thumbsUpIcon} />
</template>

We'll just have to refactor the docs/links.ts file because it defines a few icons for some cards on the home page, and we can't use assets imports in that file currently because it's imported from .vitepress/config.ts, which is executed in a Node context, not in a Vite (bundler) context.

Either approach is fine with me. :)

…g icons

bolt-new-by-stackblitz · 2023-10-30T19:08:22Z

Run & review this pull request in StackBlitz Codeflow.

stackblitz-staging · 2023-10-30T19:08:22Z

Run & review this pull request in StackBlitz Codeflow.

netlify · 2023-10-30T19:08:25Z

✅ Deploy Preview for stackblitz-docs ready!

Name	Link
🔨 Latest commit	`65a8617`
🔍 Latest deploy log	https://app.netlify.com/sites/stackblitz-docs/deploys/653ffff0f59a7f00081ffaad
😎 Deploy Preview	https://deploy-preview-173--stackblitz-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

fvsch · 2023-10-30T19:11:14Z

.vitepress/theme/components/CardGrid.vue

@@ -23,14 +22,14 @@ defineProps<{ links: any[] }>();
  gap: 24px;
  list-style: none;

-  @media (min-width: $bp-medium) {
+  @media (min-width: 680px) {


Not directly required by this PR: I removed the .vitepress/theme/styles/vars.scss file which was defining a few breakpoint values because:

it defined 3 values and we are using more than that;

the same 3 values defined in Sass variables were also often hardcoded in other .scss files.

Using breakpoints defined in Sass variables was the exception and not the rule, so using hardcoded breakpoint values everywhere makes these styles more consistent and removes a layer of indirection.

fvsch · 2023-10-30T19:14:06Z

.vitepress/theme/components/Feedback/Feedback.vue

+  <div class="feedbackContainer">
+    <form name="webcontainer-api-doc-feedback" data-netlify="true" hidden>
+      <textarea name="feedback"></textarea>
+      <input name="wasHelpful" />
+      <input name="page" />
+    </form>


Whitespace formatting by Prettier is confusing GitHub's diff view quite a bit here.

The only changes in this component are about SVG icons:

- <span class="icon thumbsUp"></span> + <SvgIcon class="thumbsUp" icon="fa-thumbs-up" size="12px" />

And some removed CSS in the <style> tag below.

fvsch · 2023-10-30T19:17:46Z

.vitepress/theme/data/types.ts

+export interface CardLink {
+  bgImg?: 'bolt' | 'squares' | 'steps';
+  description: string;
+  icon?: string;
+  large?: boolean;
+  title: string;
+  url: string;
+}


This object is used to type some content in docs/links.ts, and is identical to the props for the CardLink.vue component, but in that component we cannot define the props like this:

import type { CardLink as CardLinkProps } from '@theme/data/types'; defineProps<CardLinkProps>();

Because it breaks the Vue SFC compiler. It's a known issue in Vue. You have to pass at least the prop keys literally:

defineProps<{ bgImg?: 'bolt' | 'squares' | 'steps'; description: string; icon?: string; large?: boolean; title: string; url: string; }>();

And you can only used imported types for prop values.

So in our case, we end up with duplication.

fvsch · 2023-10-30T19:19:39Z

docs/codeflow/integrating-web-publisher.md

-| <img alt="Edit in Web Publisher" src="/img/edit_in_web_publisher.svg" /> | <a href="/img/edit_in_web_publisher.svg" target="_blank">edit_in_web_publisher.svg</a> |
-| <img alt="Edit in Web Publisher" src="/img/edit_in_web_publisher_small.svg" /> | <a href="/img/edit_in_web_publisher_small.svg" target="_blank">edit_in_web_publisher_small.svg</a> |
+| <img alt="Edit in Web Publisher" src="https://developer.stackblitz.com/img/edit_in_web_publisher.svg" /> | <a href="https://developer.stackblitz.com/img/edit_in_web_publisher.svg" target="_blank">edit_in_web_publisher.svg</a> |
+| <img alt="Edit in Web Publisher" src="https://developer.stackblitz.com/img/edit_in_web_publisher_small.svg" /> | <a href="https://developer.stackblitz.com/img/edit_in_web_publisher_small.svg" target="_blank">edit_in_web_publisher_small.svg</a> |


I changed links to our “Edit in …” button images to be absolute URLs, because we don't want those URLs to change if we set a base config value other than '/' in .vitepress/config.ts.

fvsch · 2023-10-30T19:20:36Z

docs/enterprise/configuring-dns.md

 2. Retrieve the existing StackBlitz application certificate and key via `kubectl get secret -o jsonpath={.data} stackblitz-tls-secret`
-3. Create a new yaml file on the host VM called new-kotsadm-tls.yaml based on the template below:
-```apiVersion: v1


Fixed a formatting issue: here the apiVersion part was understood as a language specifier, and not as the first line of the preformatted content.

fvsch · 2023-10-30T19:21:43Z

docs/links.ts

-    bgImgLight: '/img/theme/link-bg-bolt-light.jpg',
-    bgImgDark: '/img/theme/link-bg-bolt-dark.jpg',
+    bgImg: 'bolt',


Responsibility for finding the exact image URLs for the 'bolt' background is moved to the CardLink component.

ykmsd

Looks good to me, I like the proposed solution for SVG icon component, but I'm fine with both ways if somebody prefers the other way.

Also not related to this PR, but while I was testing it out, I realised the feedback component is broken and we haven't sent feedback for a while 😭 I will open a PR to fix it.

fvsch added 11 commits October 30, 2023 15:22

Add base URL to VitePress config

7b27e0f

Move Gilroy fonts to .vitepress/theme/fonts

d41a6a8

Move icons folder to theme and load icons with Vite

1ae72ba

Fix typo in YAML example

617cab2

Use full URLs for Edit in StackBlitz and related buttons

1b19fce

Move CardLink background images to .vitepress/theme/img

3ff3dc7

Better data types for card links

01c78cb

Cleanup: remove duplicate LoadingIcon.vue, inline BooksIcon.vue

753e3ef

Use withBase helper in link components

f728df8

Use base folder in VitePress outDir

6e4b9f4

Use url('@theme/path/to/asset') pattern in CSS instead of pre-bundlin…

65a8617

…g icons

fvsch commented Oct 30, 2023

View reviewed changes

fvsch requested review from sulco, ykmsd and donmckenna October 30, 2023 19:22

ykmsd approved these changes Oct 31, 2023

View reviewed changes

fvsch merged commit 810a868 into main Oct 31, 2023

fvsch deleted the fvsch/base-url branch October 31, 2023 10:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: allow serving documentation site on a subpath #173

feat: allow serving documentation site on a subpath #173

Uh oh!

fvsch commented Oct 30, 2023

Uh oh!

bolt-new-by-stackblitz bot commented Oct 30, 2023

Uh oh!

stackblitz-staging bot commented Oct 30, 2023

Uh oh!

netlify bot commented Oct 30, 2023 •

edited

Loading

Uh oh!

fvsch Oct 30, 2023

Uh oh!

fvsch Oct 30, 2023

Uh oh!

fvsch Oct 30, 2023

Uh oh!

fvsch Oct 30, 2023

Uh oh!

fvsch Oct 30, 2023

Uh oh!

fvsch Oct 30, 2023

Uh oh!

ykmsd left a comment

Uh oh!

Uh oh!

feat: allow serving documentation site on a subpath #173

feat: allow serving documentation site on a subpath #173

Uh oh!

Conversation

fvsch commented Oct 30, 2023

Fixing URLs in components

Fixing links to assets (icons, images, fonts)

The <SvgIcon /> component

Uh oh!

bolt-new-by-stackblitz bot commented Oct 30, 2023

Uh oh!

stackblitz-staging bot commented Oct 30, 2023

Uh oh!

netlify bot commented Oct 30, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for stackblitz-docs ready!

Uh oh!

fvsch Oct 30, 2023

Choose a reason for hiding this comment

Uh oh!

fvsch Oct 30, 2023

Choose a reason for hiding this comment

Uh oh!

fvsch Oct 30, 2023

Choose a reason for hiding this comment

Uh oh!

fvsch Oct 30, 2023

Choose a reason for hiding this comment

Uh oh!

fvsch Oct 30, 2023

Choose a reason for hiding this comment

Uh oh!

fvsch Oct 30, 2023

Choose a reason for hiding this comment

Uh oh!

ykmsd left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

The `<SvgIcon />` component

netlify bot commented Oct 30, 2023 •

edited

Loading