feat(docs): improved SEO (#DS-4376)

apps/docs/e2e.playwright-spec.ts

@@ -27,7 +27,7 @@ test.describe('docs app', () => {
         await page.goto('/en');
         await waitForHydration(page);
 
-        await expect(page).toHaveTitle('Koobiq');
+        await expect(page).toHaveTitle('Koobiq — Angular design system');
         await expect(page.locator('.docs-welcome__header')).toContainText('Koobiq design system');
     });
 
@@ -45,8 +45,11 @@ test.describe('docs app', () => {
         await page.goto('/en/components/alert/overview');
         await waitForHydration(page);
 
-        await expect(page).toHaveTitle('Alert · Koobiq');
-        await expect(page.locator('meta[name="description"]')).toHaveAttribute('content', /Koobiq/);
+        await expect(page).toHaveTitle('Alert — Overview · Koobiq');
+        await expect(page.locator('meta[name="description"]')).toHaveAttribute(
+            'content',
+            'Shows important information on a page. Can contain a hint, signal a status change, or indicate a problem.'
+        );
         await expect(page.locator('link[rel="canonical"]')).toHaveAttribute(
             'href',
             'https://koobiq.io/en/components/alert/overview'
@@ -61,9 +64,11 @@ test.describe('docs app', () => {
 
         await page.getByRole('tab', { name: 'API', exact: true }).click();
         await expect(page).toHaveURL(/\/en\/components\/select\/api$/);
+        await expect(page).toHaveTitle('Select — API · Koobiq');
 
         await page.getByRole('tab', { name: 'Examples', exact: true }).click();
         await expect(page).toHaveURL(/\/en\/components\/select\/examples$/);
+        await expect(page).toHaveTitle('Select — Examples · Koobiq');
     });
 
     test('shows the source of a live example', async ({ page }) => {
@@ -146,3 +151,30 @@ test.describe('docs app', () => {
         await expect(cell).toHaveAttribute('tabindex', '0');
     });
 });
+
+test.describe('prerendered SEO metadata', () => {
+    test.use({ javaScriptEnabled: false });
+
+    test('is present in the initial HTML without hydration', async ({ page }) => {
+        await page.goto('/en/components/alert/overview');
+
+        await expect(page).toHaveTitle('Alert — Overview · Koobiq');
+        await expect(page.locator('html')).toHaveAttribute('lang', 'en');
+        await expect(page.locator('meta[name="description"]')).toHaveAttribute(
+            'content',
+            'Shows important information on a page. Can contain a hint, signal a status change, or indicate a problem.'
+        );
+        await expect(page.locator('meta[property="og:image"]')).toHaveAttribute(
+            'content',
+            'https://koobiq.io/assets/images/welcome/alerts-light.png'
+        );
+        await expect(page.locator('link[rel="canonical"]')).toHaveAttribute(
+            'href',
+            'https://koobiq.io/en/components/alert/overview'
+        );
+        await expect(page.locator('link[rel="alternate"][hreflang="ru"]')).toHaveAttribute(
+            'href',
+            'https://koobiq.io/ru/components/alert/overview'
+        );
+    });
+});

apps/docs/src/app/components/component-viewer/component-viewer.template.html

@@ -12,7 +12,9 @@
                         {{ t('overviewTab') }}
                     </a>
                     @if (structureItem.hasApi) {
-                        <a kbqTabLink routerLinkActive="kbq-selected" [routerLink]="structureItemTab.Api">API</a>
+                        <a kbqTabLink routerLinkActive="kbq-selected" [routerLink]="structureItemTab.Api">
+                            {{ t('apiTab') }}
+                        </a>
                     }
                     @if (structureItem.hasExamples) {
                         <a kbqTabLink routerLinkActive="kbq-selected" [routerLink]="structureItemTab.Examples">

apps/docs/src/app/page-paths.spec.ts

@@ -0,0 +1,38 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { DOCS_SUPPORTED_LOCALES } from './constants/locale';
+import { docsGetIndexablePagePaths } from './page-paths';
+
+describe(docsGetIndexablePagePaths.name, () => {
+    it('contains welcome, overview, API, examples and icons pages without duplicates', () => {
+        const paths = docsGetIndexablePagePaths();
+
+        expect(paths).toContain('');
+        expect(paths).toContain('components/alert/overview');
+        expect(paths).toContain('components/alert/api');
+        expect(paths).toContain('components/select/examples');
+        expect(paths).toContain('icons');
+        expect(new Set(paths).size).toBe(paths.length);
+    });
+
+    it('stays synchronized with the committed prerender route registry', () => {
+        const expectedRoutes = DOCS_SUPPORTED_LOCALES.flatMap((locale) =>
+            docsGetIndexablePagePaths().map((path) => `/${locale}${path ? `/${path}` : ''}`)
+        );
+        const prerenderRoutes = readFileSync(join(process.cwd(), 'apps/docs/src/prerender-routes.txt'), 'utf8')
+            .trim()
+            .split('\n');
+
+        expect(prerenderRoutes).toEqual(expectedRoutes);
+    });
+
+    it('stays synchronized with the committed sitemap', () => {
+        const expectedUrls = docsGetIndexablePagePaths().flatMap((path) =>
+            DOCS_SUPPORTED_LOCALES.map((locale) => `https://koobiq.io/${locale}${path ? `/${path}` : ''}`)
+        );
+        const sitemap = readFileSync(join(process.cwd(), 'apps/docs/src/sitemap.xml'), 'utf8');
+        const sitemapUrls = Array.from(sitemap.matchAll(/<loc>(.*?)<\/loc>/g), ([, url]) => url);
+
+        expect(sitemapUrls).toEqual(expectedUrls);
+    });
+});

apps/docs/src/app/page-paths.ts

@@ -0,0 +1,28 @@
+import {
+    docsGetItems,
+    DocsStructureCategoryId,
+    DocsStructureItemId,
+    DocsStructureItemTab,
+    DocsStructureTokensTab
+} from './structure';
+
+/**
+ * Returns every localized-content path that should be prerendered and indexed, without a locale
+ * prefix. An empty string represents the localized welcome page.
+ */
+export const docsGetIndexablePagePaths = (): string[] => {
+    const paths = docsGetItems().flatMap(({ categoryId, id, hasApi, hasExamples }) => {
+        if (id === DocsStructureItemId.DesignTokens) {
+            return Object.values(DocsStructureTokensTab).map((tab) => `${categoryId}/${id}/${tab}`);
+        }
+
+        const tabs = [`${categoryId}/${id}/${DocsStructureItemTab.Overview}`];
+
+        if (hasApi) tabs.push(`${categoryId}/${id}/${DocsStructureItemTab.Api}`);
+        if (hasExamples) tabs.push(`${categoryId}/${id}/${DocsStructureItemTab.Examples}`);
+
+        return tabs;
+    });
+
+    return ['', ...paths, DocsStructureCategoryId.Icons];
+};