Skip to content

Commit 858c565

Browse files
chore: add api-docs package with new static website (#9803)
Co-authored-by: web-padawan <[email protected]>
1 parent 8ebeeec commit 858c565

21 files changed

+2128
-54
lines changed

.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,7 @@ scripts/check-releases.html
3838

3939
# TypeScript output
4040
tsconfig.build.tsbuildinfo
41+
42+
# API docs generated files
43+
api-docs/dist
44+
api-docs/content/elements

api-docs/.eleventy.js

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
import syntaxHighlightPlugin from '@11ty/eleventy-plugin-syntaxhighlight';
2+
import markdownIt from 'markdown-it';
3+
import markdownItAnchor from 'markdown-it-anchor';
4+
import { parse } from 'node-html-parser';
5+
6+
export default function (config) {
7+
// See https://www.11ty.dev/docs/config/
8+
config.setInputDirectory('content');
9+
config.setOutputDirectory('dist');
10+
config.setDataDirectory('../_data');
11+
config.setIncludesDirectory('../_includes');
12+
13+
// See https://www.11ty.dev/docs/languages/markdown/
14+
config.setLibrary(
15+
'md',
16+
markdownIt({
17+
html: true,
18+
linkify: true,
19+
}).use(markdownItAnchor, {
20+
slugify: config.getFilter('slugify'),
21+
level: [1, 2, 3, 4],
22+
permalink: markdownItAnchor.permalink.ariaHidden({
23+
placement: 'after',
24+
class: 'anchor-link',
25+
symbol: '#',
26+
}),
27+
}),
28+
);
29+
30+
config.addPlugin(syntaxHighlightPlugin, {
31+
preAttributes: {
32+
class: ({ language }) => `code-block language-${language}`,
33+
},
34+
});
35+
36+
config.addPassthroughCopy('css');
37+
config.addPassthroughCopy('js');
38+
config.addPassthroughCopy({ img: '/' });
39+
40+
// Copy markdown files for "view as MD"
41+
config.addPassthroughCopy({ 'content/elements': 'markdown' });
42+
43+
config.addCollection('elements', (api) => {
44+
return api.getFilteredByGlob('./content/elements/*.md').sort((a, b) => {
45+
return a.data.title.localeCompare(b.data.title);
46+
});
47+
});
48+
49+
// Table of contents
50+
config.addFilter('toc', (content) => {
51+
const html = parse(content);
52+
const headings = html.querySelectorAll('h1, h2, h3, h4');
53+
const toc = headings.map((heading) => {
54+
// Remove anchor links
55+
heading.querySelectorAll('[aria-hidden=true]').forEach((el) => el.remove());
56+
57+
const id = heading.attributes.id;
58+
const text = heading.innerText;
59+
const level = parseInt(heading.tagName.replace('H', ''), 10);
60+
61+
return { id, text, level };
62+
});
63+
64+
// The page title already uses an h1, so it's recommended to start with h2
65+
// in the content. If the first heading is an h2 or higher, we'll adjust the
66+
// levels to start with level 1 to avoid unnecessary indentation in the TOC.
67+
const minLevel = Math.min(...toc.map((item) => item.level));
68+
if (minLevel > 1)
69+
toc.forEach((item) => {
70+
item.level -= minLevel - 1;
71+
});
72+
73+
return toc;
74+
});
75+
}

api-docs/_data/metadata.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"title": "Vaadin WC API reference",
3+
"description": "Vaadin web components API documentation"
4+
}

api-docs/_includes/layout.njk

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
toc: true
3+
---
4+
5+
<!doctype html>
6+
<html lang="en">
7+
<head>
8+
<meta charset="UTF-8" />
9+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
10+
<meta name="description" content="{{ description or metadata.description }}" />
11+
<title>{{ title or metadata.title }}</title>
12+
<meta name="generator" content="{{ eleventy.generator }}" />
13+
<link rel="shortcut icon" href="/favicon.ico" type="image/x-icon" />
14+
<link href="/css/index.css" rel="stylesheet" />
15+
</head>
16+
17+
<body>
18+
<div class="app-layout">
19+
{% include "partials/header.njk" %}
20+
21+
<div class="app-layout__wrapper">
22+
{% include "partials/navigation.njk" %}
23+
24+
<div class="app-layout__content">
25+
<div class="page">
26+
<main class="page__main">
27+
<article>
28+
<div class="page__header">
29+
<h1 class="page__title">
30+
{{ title }}
31+
</h1>
32+
33+
{% if toc %}
34+
{% include "partials/actions.njk" %}
35+
{% endif %}
36+
</div>
37+
38+
<div class="article">
39+
{{ content | safe }}
40+
</div>
41+
</article>
42+
</main>
43+
44+
{% if toc %}
45+
<div class="page__panel">
46+
{% include 'partials/toc.njk' %}
47+
</div>
48+
{% endif %}
49+
</div>
50+
</div>
51+
</div>
52+
</div>
53+
54+
<script src="/js/copy-code.js"></script>
55+
<script src="/js/copy-markdown.js"></script>
56+
</body>
57+
</html>
Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
<div class="actions">
2+
<button id="copy-markdown" class="actions__btn">
3+
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
4+
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
5+
<path d="M3 5m0 2a2 2 0 0 1 2 -2h14a2 2 0 0 1 2 2v10a2 2 0 0 1 -2 2h-14a2 2 0 0 1 -2 -2z" />
6+
<path d="M7 15v-6l2 2l2 -2v6" />
7+
<path d="M14 13l2 2l2 -2m-2 2v-6" />
8+
</svg>
9+
<span>Copy as MD</span>
10+
</button>
11+
<a class="actions__btn" href="/markdown/{{ element | slugify }}.md" target="_blank">
12+
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
13+
<path stroke="none" d="M0 0h24v24H0z" fill="none" />
14+
<path d="M12 6h-6a2 2 0 0 0 -2 2v10a2 2 0 0 0 2 2h10a2 2 0 0 0 2 -2v-6" />
15+
<path d="M11 13l9 -9" />
16+
<path d="M15 4h5v5" />
17+
</svg>
18+
<span>View as MD</span>
19+
</a>
20+
</div>
Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<header class="app-header">
2+
3+
<label for="navigation" class="icon-btn">
4+
<svg xmlns="http://www.w3.org/2000/svg" width="1.125em" height="1.125em" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
5+
<path d="M4 12h16"></path><path d="M4 18h16"></path><path d="M4 6h16"></path>
6+
</svg>
7+
</label>
8+
9+
<a href="/" class="app-header__title">
10+
{{ metadata.title }}
11+
</a>
12+
</header>
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<input type="checkbox" name="navigation" id="navigation" class="visually-hidden" />
2+
3+
<div class="app-layout__sidebar">
4+
<div class="app-layout__sidebar-inner">
5+
6+
<nav class="nav-section">
7+
<h3 class="nav-section__title">
8+
Elements
9+
</h3>
10+
<ul role="list" class="nav-list">
11+
{% for doc in collections.elements %}
12+
<li>
13+
<a href="{{ doc.url }}" class="nav-list__link">
14+
{{ doc.data.title }}
15+
</a>
16+
</li>
17+
{% endfor %}
18+
</ul>
19+
</nav>
20+
</div>
21+
</div>
Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
<aside>
2+
{% set toc = content | toc %}
3+
{% if (toc | length) %}
4+
<div class="toc">
5+
<h2 class="toc__label" id="app-panel-toc">
6+
On this page
7+
</h2>
8+
<ul class="toc__list" role="list" aria-labelledby="app-panel-toc">
9+
{% for item in toc %}
10+
<li style="--level: {{ item.level }}" class="toc__item">
11+
<a href="#{{ item.id }}" class="toc__link">
12+
{{ item.text | safe }}
13+
</a>
14+
</li>
15+
{% endfor %}
16+
</ul>
17+
</div>
18+
{% endif %}
19+
</aside>

api-docs/content/content.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"layout": "layout.njk"
3+
}

api-docs/content/index.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: Vaadin WC API Reference
3+
permalink: /
4+
toc: false
5+
---
6+
7+
This is the API reference for the Vaadin Web Components. It contains information about the elements, their properties, methods, and events.
8+
9+
This reference is intended for developers using either the plain Web Components, or their React wrappers, with either Javascript or TypeScript.
10+
11+
The API documentation is generated from JSDoc annotations in the components source files. If you want to contribute to the documentation, please check corresponding packages.
12+
13+
For the full component documentation, including examples and guides, please refer to the [Vaadin Components documentation](https://vaadin.com/docs/latest/components).

0 commit comments

Comments
 (0)