diff --git a/examples/docs/package.json b/examples/docs/package.json index fbe9a654c..ea86fdb60 100644 --- a/examples/docs/package.json +++ b/examples/docs/package.json @@ -9,6 +9,7 @@ "preview": "astro preview" }, "dependencies": { + "@astrojs/docs": "^0.0.1", "@docsearch/react": "^1.0.0-alpha.27" }, "devDependencies": { diff --git a/examples/docs/public/default-og-image.png b/examples/docs/public/default-og-image.png deleted file mode 100644 index 97903207e..000000000 Binary files a/examples/docs/public/default-og-image.png and /dev/null differ diff --git a/examples/docs/public/index.css b/examples/docs/public/index.css deleted file mode 100644 index aadc5c2f5..000000000 --- a/examples/docs/public/index.css +++ /dev/null @@ -1,386 +0,0 @@ -* { - box-sizing: border-box; - margin: 0; -} - -/* Global focus outline reset */ -*:focus:not(:focus-visible) { - outline: none; -} - -:root { - --user-font-scale: 1rem - 16px; - --max-width: calc(100% - 1rem); -} - -@media (min-width: 50em) { - :root { - --max-width: 46em; - } -} - -body { - display: flex; - flex-direction: column; - min-height: 100vh; - font-family: var(--font-body); - font-size: 1rem; - font-size: clamp(0.9rem, 0.75rem + 0.375vw + var(--user-font-scale), 1rem); - line-height: 1.5; - max-width: 100vw; -} - -nav ul { - list-style: none; - padding: 0; -} - -.content > section > * + * { - margin-top: 1.25rem; -} - -.content > section > :first-child { - margin-top: 0; -} - -/* Typography */ -h1, -h2, -h3, -h4, -h5, -h6 { - margin-bottom: 1rem; - font-weight: bold; - line-height: 1; -} - -h1, -h2 { - max-width: 40ch; -} - -:is(h2, h3):not(:first-child) { - margin-top: 3rem; -} - -:is(h4, h5, h6):not(:first-child) { - margin-top: 2rem; -} - -h1 { - font-size: 3.25rem; - font-weight: 800; -} - -h2 { - font-size: 2.5rem; -} - -h3 { - font-size: 1.75rem; -} - -h4 { - font-size: 1.3rem; -} - -h5 { - font-size: 1rem; -} - -p { - line-height: 1.65em; -} - -.content ul { - line-height: 1.1em; -} - -p, -.content ul { - color: var(--theme-text-light); -} - -small, -.text_small { - font-size: 0.833rem; -} - -a { - color: var(--theme-text-accent); - font-weight: 400; - text-underline-offset: 0.08em; - align-items: center; - gap: 0.5rem; -} - -article > section :is(ul, ol) > * + * { - margin-top: 0.75rem; -} - -article > section nav :is(ul, ol) > * + * { - margin-top: inherit; -} - -article > section li > :is(p, pre, blockquote):not(:first-child) { - margin-top: 1rem; -} - -article > section :is(ul, ol) { - padding-left: 1em; -} - -article > section nav :is(ul, ol) { - padding-left: inherit; -} - -article > section nav { - margin-top: 1rem; - margin-bottom: 2rem; -} - -article > section ::marker { - font-weight: bold; - color: var(--theme-text-light); -} - -article > section iframe { - width: 100%; - height: auto; - aspect-ratio: 16 / 9; -} - -a > code:not([class*='language']) { - position: relative; - color: var(--theme-text-accent); - background: transparent; - text-underline-offset: var(--padding-block); -} - -a > code:not([class*='language'])::before { - content: ''; - position: absolute; - top: 0; - right: 0; - bottom: 0; - left: 0; - display: block; - background: var(--theme-accent); - opacity: var(--theme-accent-opacity); - border-radius: var(--border-radius); -} - -a:hover, -a:focus { - text-decoration: underline; -} - -a:focus { - outline: 2px solid currentColor; - outline-offset: 0.25em; -} - -strong { - font-weight: 600; - color: inherit; -} - -/* Supporting Content */ -code { - font-family: var(--font-mono); - font-size: 0.85em; -} - -code:not([class*='language']) { - --border-radius: 3px; - --padding-block: 0.2rem; - --padding-inline: 0.4rem; - color: var(--theme-code-inline-text); - background-color: var(--theme-code-inline-bg); - padding: var(--padding-block) var(--padding-inline); - margin: calc(var(--padding-block) * -1) -0.125em; - border-radius: var(--border-radius); - box-shadow: 0 2px 1px 0 rgba(0, 0, 0, 0.08); -} - -pre > code:not([class*='language']) { - background-color: transparent; - padding: 0; - margin: 0; - border-radius: 0; - color: inherit; -} - -pre > code { - font-size: 1em; -} - -table, -pre { - position: relative; - --padding-block: 1rem; - --padding-inline: 2rem; - padding: var(--padding-block) var(--padding-inline); - padding-right: calc(var(--padding-inline) * 2); - margin-left: calc(var(--padding-inline) * -1); - margin-right: calc(var(--padding-inline) * -1); - font-family: var(--font-mono); - - line-height: 1.5; - font-size: 0.85em; - overflow-y: hidden; - overflow-x: auto; -} - -table { - width: 100%; - padding: var(--padding-block) 0; - margin: 0; - border-collapse: collapse; -} - -/* Zebra striping */ -tr:nth-of-type(odd) { - background: var(--theme-bg-hover); -} -th { - background: var(--color-black); - color: var(--theme-color); - font-weight: bold; -} -td, -th { - padding: 6px; - text-align: left; -} - -pre { - background-color: var(--theme-code-bg); - color: var(--theme-code-text); -} - -blockquote code:not([class*='language']) { - background-color: var(--theme-bg); -} - -@media (min-width: 37.75em) { - pre { - --padding-inline: 1.25rem; - border-radius: 8px; - margin-left: 0; - margin-right: 0; - } -} - -blockquote { - margin: 2rem 0; - padding: 1.25em 1.5rem; - border-left: 3px solid var(--theme-text-light); - background-color: var(--theme-bg-offset); - border-radius: 0 0.25rem 0.25rem 0; - line-height: 1.7; -} - -img { - max-width: 100%; -} - -.flex { - display: flex; - align-items: center; -} - -button { - display: flex; - align-items: center; - justify-items: center; - gap: 0.25em; - padding: 0.33em 0.67em; - border: 0; - background: var(--theme-bg); - display: flex; - font-size: 1rem; - align-items: center; - gap: 0.25em; - border-radius: 99em; - color: var(--theme-text); - background-color: var(--theme-bg); -} - -h2.heading { - font-size: 1rem; - font-weight: 700; - padding: 0.1rem 1rem; - text-transform: uppercase; - margin-bottom: 0.5rem; -} - -.header-link { - font-size: 1rem; - padding: 0.1rem 0 0.1rem 1rem; - border-left: 4px solid var(--theme-divider); -} - -.header-link:hover, -.header-link:focus { - border-left-color: var(--theme-accent); - color: var(--theme-accent); -} -.header-link:focus-within { - color: var(--theme-text-light); - border-left-color: hsla(var(--color-gray-40), 1); -} -.header-link svg { - opacity: 0.6; -} -.header-link:hover svg { - opacity: 0.8; -} -.header-link a { - display: inline-flex; - gap: 0.5em; - width: 100%; -} - -.header-link.depth-3 { - padding-left: 2rem; -} -.header-link.depth-4 { - padding-left: 3rem; -} - -.header-link a { - font: inherit; - color: inherit; - text-decoration: none; -} - -/* Screenreader Only Text */ -.sr-only { - position: absolute; - width: 1px; - height: 1px; - padding: 0; - margin: -1px; - overflow: hidden; - clip: rect(0, 0, 0, 0); - white-space: nowrap; - border-width: 0; -} - -.focus\:not-sr-only:focus, -.focus\:not-sr-only:focus-visible { - position: static; - width: auto; - height: auto; - padding: 0; - margin: 0; - overflow: visible; - clip: auto; - white-space: normal; -} - -:target { - scroll-margin: calc(var(--theme-sidebar-offset, 5rem) + 2rem) 0 2rem; -} diff --git a/examples/docs/public/make-scrollable-code-focusable.js b/examples/docs/public/make-scrollable-code-focusable.js deleted file mode 100644 index 35f104923..000000000 --- a/examples/docs/public/make-scrollable-code-focusable.js +++ /dev/null @@ -1,3 +0,0 @@ -Array.from(document.getElementsByTagName('pre')).forEach((element) => { - element.setAttribute('tabindex', '0'); -}); diff --git a/examples/docs/src/components/Footer/Footer.astro b/examples/docs/src/components/Footer/Footer.astro deleted file mode 100644 index 48de51054..000000000 --- a/examples/docs/src/components/Footer/Footer.astro +++ /dev/null @@ -1,16 +0,0 @@ ---- -import AvatarList from './AvatarList.astro'; -const { path } = Astro.props; ---- - - - - diff --git a/examples/docs/src/components/Head.astro b/examples/docs/src/components/Head.astro new file mode 100644 index 000000000..33296c20f --- /dev/null +++ b/examples/docs/src/components/Head.astro @@ -0,0 +1,52 @@ +--- +// The Component - Responsible for site-wide `` metadata and SEO tags. +import * as CONFIG from '../config.ts'; +export interface Props { + /** A markdown content prop. */ + content?: any; +} + +const {content = {}} = Astro.props as Props; +const siteTitle: string = CONFIG.SITE.title; +const pageTitle: string = content.title ? `${content.title} | ${siteTitle}` : siteTitle; +const pageDescription: string = content.description || CONFIG.SITE.description; +const lang: string = content.lang || CONFIG.SITE.lang; +const imageURL: string = content.image?.url || CONFIG.SITE.image.url; +const imageAlt: string = content.image?.alt || CONFIG.SITE.image.alt; +const canonicalURL: string = Astro.request.canonicalURL; +const twitter: string | undefined = CONFIG.TWITTER; +--- + + + + + + + + +{pageTitle} + + + + + + + + + + + + + + + + + + + + + +{twitter && } +{twitter && } + + diff --git a/examples/docs/src/components/HeadCommon.astro b/examples/docs/src/components/HeadCommon.astro deleted file mode 100644 index 83045c0d1..000000000 --- a/examples/docs/src/components/HeadCommon.astro +++ /dev/null @@ -1,40 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/examples/docs/src/components/HeadSEO.astro b/examples/docs/src/components/HeadSEO.astro deleted file mode 100644 index 268809a87..000000000 --- a/examples/docs/src/components/HeadSEO.astro +++ /dev/null @@ -1,40 +0,0 @@ ---- -import {SITE, OPEN_GRAPH} from '../config.ts'; -export interface Props { - content: any, - site: any, - canonicalURL: URL | string, -}; -const { content = {}, canonicalURL } = Astro.props; -const formattedContentTitle = content.title ? `${content.title} 🚀 ${SITE.title}` : SITE.title; -const imageSrc = content?.image?.src ?? OPEN_GRAPH.image.src; -const canonicalImageSrc = new URL(imageSrc, Astro.site); -const imageAlt = content?.image?.alt ?? OPEN_GRAPH.image.alt; ---- - - - - - - - - - - - - - - - - - - - - - - diff --git a/examples/docs/src/components/PageContent/PageContent.astro b/examples/docs/src/components/PageContent/PageContent.astro deleted file mode 100644 index fd1e9d242..000000000 --- a/examples/docs/src/components/PageContent/PageContent.astro +++ /dev/null @@ -1,41 +0,0 @@ ---- -const {content, githubEditUrl} = Astro.props; -const title = content.title; -const headers = content.astro.headers; -import MoreMenu from '../RightSidebar/MoreMenu.astro'; -import TableOfContents from '../RightSidebar/TableOfContents.tsx'; ---- - -
-
-

{title}

- - -
- -
\ No newline at end of file diff --git a/examples/docs/src/components/RightSidebar/RightSidebar.astro b/examples/docs/src/components/RightSidebar/RightSidebar.astro deleted file mode 100644 index ed1dd37cc..000000000 --- a/examples/docs/src/components/RightSidebar/RightSidebar.astro +++ /dev/null @@ -1,25 +0,0 @@ ---- -import TableOfContents from './TableOfContents.jsx'; -import MoreMenu from './MoreMenu.astro'; -const {content, githubEditUrl} = Astro.props; -const headers = content.astro.headers; ---- - - \ No newline at end of file diff --git a/examples/docs/src/config.ts b/examples/docs/src/config.ts index a892aedda..52d11f1ab 100644 --- a/examples/docs/src/config.ts +++ b/examples/docs/src/config.ts @@ -1,15 +1,12 @@ export const SITE = { title: 'Your Documentation Website', description: 'Your website description.', - defaultLanguage: 'en_US', -}; - -export const OPEN_GRAPH = { + lang: 'en', + dir: 'ltr', image: { src: 'https://github.com/snowpackjs/astro/blob/main/assets/social/banner.png?raw=true', - alt: 'astro logo on a starry expanse of space,' + ' with a purple saturn-like planet floating in the right foreground', + alt: 'The Astro logo over an outerspace background image, with stars and planets.', }, - twitter: 'astrodotbuild', }; export const KNOWN_LANGUAGES = { @@ -17,10 +14,14 @@ export const KNOWN_LANGUAGES = { }; // Uncomment this to add an "Edit this page" button to every page of documentation. -// export const GITHUB_EDIT_URL = `https://github.com/snowpackjs/astro/blob/main/docs/`; +// The path of the page content is always appended to this URL. +// export const EDIT_URL = `https://github.com/snowpackjs/astro/blob/main/docs/`; // Uncomment this to add an "Join our Community" button to every page of documentation. -// export const COMMUNITY_INVITE_URL = `https://astro.build/chat`; +// export const COMMUNITY_URL = `https://astro.build/chat`; + +// Uncomment this to enable the Twitter SEO meta tag. +// export const TWITTER = 'astrodotbuild'; // Uncomment this to enable site search. // See "Algolia" section of the README for more information. diff --git a/examples/docs/src/languages.ts b/examples/docs/src/languages.ts deleted file mode 100644 index 389c3d7a7..000000000 --- a/examples/docs/src/languages.ts +++ /dev/null @@ -1,8 +0,0 @@ -import { KNOWN_LANGUAGES } from './config.js'; - -export const KNOWN_LANGUAGE_CODES = Object.values(KNOWN_LANGUAGES); - -export function getLanguageFromURL(pathname: string) { - const langCodeMatch = pathname.match(/\/([a-z]{2}-?[A-Z]{0,2})\//); - return langCodeMatch ? langCodeMatch[1] : 'en'; -} diff --git a/examples/docs/src/layouts/MainLayout.astro b/examples/docs/src/layouts/MainLayout.astro index 620f2e06b..8cc161801 100644 --- a/examples/docs/src/layouts/MainLayout.astro +++ b/examples/docs/src/layouts/MainLayout.astro @@ -1,122 +1,38 @@ --- -import HeadCommon from "../components/HeadCommon.astro"; -import HeadSEO from "../components/HeadSEO.astro"; -import Header from '../components/Header/Header.astro'; -import Footer from '../components/Footer/Footer.astro'; -import PageContent from '../components/PageContent/PageContent.astro'; -import LeftSidebar from '../components/LeftSidebar/LeftSidebar.astro'; -import RightSidebar from '../components/RightSidebar/RightSidebar.astro'; -import * as CONFIG from "../config.ts"; +// - The main layout for your docs site. +// This includes all reusable UI from the '@astrojs/docs' package. +// Markdown content will be injected at the `` component. +// +// The fastest way to customize this layout is to add new components +// to any existing layout "slot". For example, `` is a custom +// component that islives in this project "src/components" directory. +// Components will end up in each slot in the order that they appear. +// +// You can also completely replace layout components like `LeftSidebar` +// and `PageContent` with your own UI. + +import {PageLayout, Header, PageContent, LeftSidebar, RightSidebar} from '@astrojs/docs'; +import Head from '../components/Head.astro'; +import * as CONFIG from '../config.ts'; + +export interface Props { + /** A markdown content prop. Automatically provided by Astro. */ + content?: any; +} const { content = {} } = Astro.props; +const dir = content.dir || CONFIG.SITE.dir; +const lang = content.lang || CONFIG.SITE.lang; const currentPage = Astro.request.url.pathname; const currentFile = `src/pages${currentPage.replace(/\/$/, "")}.md`; -const githubEditUrl = CONFIG.GITHUB_EDIT_URL && (CONFIG.GITHUB_EDIT_URL + currentFile); +const editUrlWithFile = CONFIG.EDIT_URL && (CONFIG.EDIT_URL + currentFile); --- - - - - - - {content.title ? `${content.title} 🚀 ${CONFIG.SITE.title}` : CONFIG.SITE.title} - - - - -
-
- -
- - - -
- -
- - + + +
+ + + + + + diff --git a/examples/docs/src/pages/en/introduction.md b/examples/docs/src/pages/en/introduction.md index 494496a90..e7b853de4 100644 --- a/examples/docs/src/pages/en/introduction.md +++ b/examples/docs/src/pages/en/introduction.md @@ -1,5 +1,6 @@ --- title: Introduction +lang: en layout: ../../layouts/MainLayout.astro --- diff --git a/examples/docs/src/pages/en/page-2.md b/examples/docs/src/pages/en/page-2.md index 1da681d5c..30acf356f 100644 --- a/examples/docs/src/pages/en/page-2.md +++ b/examples/docs/src/pages/en/page-2.md @@ -1,5 +1,6 @@ --- title: Page 2 +lang: en layout: ../../layouts/MainLayout.astro --- diff --git a/examples/docs/src/pages/en/page-3.md b/examples/docs/src/pages/en/page-3.md index afaebe51e..a3dd3dd24 100644 --- a/examples/docs/src/pages/en/page-3.md +++ b/examples/docs/src/pages/en/page-3.md @@ -1,5 +1,6 @@ --- title: Page 3 +lang: en layout: ../../layouts/MainLayout.astro --- diff --git a/examples/docs/src/pages/en/page-4.md b/examples/docs/src/pages/en/page-4.md index bae0d75c2..7fe5b79f4 100644 --- a/examples/docs/src/pages/en/page-4.md +++ b/examples/docs/src/pages/en/page-4.md @@ -1,5 +1,6 @@ --- title: Page 4 +lang: en layout: ../../layouts/MainLayout.astro --- diff --git a/examples/docs/src/styles/base.css b/examples/docs/src/styles/base.css new file mode 100644 index 000000000..30fa6d58c --- /dev/null +++ b/examples/docs/src/styles/base.css @@ -0,0 +1,170 @@ +* { + box-sizing: border-box; + margin: 0; + } + + /* Global focus outline reset */ + *:focus:not(:focus-visible) { + outline: none; + } + + :root { + --user-font-scale: 1rem - 16px; + --max-width: calc(100% - 1rem); + } + + @media (min-width: 50em) { + :root { + --max-width: 46em; + } + } + + body { + display: flex; + flex-direction: column; + min-height: 100vh; + font-family: var(--font-body); + font-size: 1rem; + font-size: clamp(0.9rem, 0.75rem + 0.375vw + var(--user-font-scale), 1rem); + line-height: 1.5; + max-width: 100vw; + } + + /* Supporting Content */ + nav ul { + list-style: none; + padding: 0; + } + + + table, + pre { + position: relative; + --padding-block: 1rem; + --padding-inline: 2rem; + padding: var(--padding-block) var(--padding-inline); + padding-right: calc(var(--padding-inline) * 2); + margin-left: calc(var(--padding-inline) * -1); + margin-right: calc(var(--padding-inline) * -1); + font-family: var(--font-mono); + + line-height: 1.5; + font-size: 0.85em; + overflow-y: hidden; + overflow-x: auto; + } + + table { + width: 100%; + padding: var(--padding-block) 0; + margin: 0; + border-collapse: collapse; + } + blockquote { + margin: 2rem 0; + padding: 1.25em 1.5rem; + border-left: 3px solid var(--theme-text-light); + background-color: var(--theme-bg-offset); + border-radius: 0 0.25rem 0.25rem 0; + line-height: 1.7; + } + img { + max-width: 100%; + } + .flex { + display: flex; + align-items: center; + } + button { + display: flex; + align-items: center; + justify-items: center; + gap: 0.25em; + padding: 0.33em 0.67em; + border: 0; + background: var(--theme-bg); + display: flex; + font-size: 1rem; + align-items: center; + gap: 0.25em; + border-radius: 99em; + color: var(--theme-text); + background-color: var(--theme-bg); + } + + /** Headings */ + h2.heading { + font-size: 1rem; + font-weight: 700; + padding: 0.1rem 1rem; + text-transform: uppercase; + margin-bottom: 0.5rem; + } + .header-link { + font-size: 1rem; + line-height: 1.5; + padding: 0.1rem 0 0.1rem 0.75rem; + margin-left: 0.25rem; + border-left: 4px solid var(--theme-divider); + } + .header-link:hover, + .header-link:focus { + border-left-color: var(--theme-accent); + color: var(--theme-accent); + } + .header-link:focus-within { + color: var(--theme-text-light); + border-left-color: hsla(var(--color-gray-40), 1); + } + .header-link svg { + opacity: 0.6; + } + .header-link:hover svg { + opacity: 0.8; + } + .header-link a { + display: inline-flex; + gap: 0.5em; + width: 100%; + } + .header-link.depth-3 { + padding-left: 2rem; + } + .header-link.depth-4 { + padding-left: 3rem; + } + .header-link a { + font: inherit; + color: inherit; + text-decoration: none; + } + + /* Screenreader Only Text */ + .sr-only { + position: absolute; + width: 1px; + height: 1px; + padding: 0; + margin: -1px; + overflow: hidden; + clip: rect(0, 0, 0, 0); + white-space: nowrap; + border-width: 0; + } + + .focus\:not-sr-only:focus, + .focus\:not-sr-only:focus-visible { + position: static; + width: auto; + height: auto; + padding: 0; + margin: 0; + overflow: visible; + clip: auto; + white-space: normal; + } + + :target { + scroll-margin: calc(var(--theme-sidebar-offset, 5rem) + 2rem) 0 2rem; + } + \ No newline at end of file diff --git a/examples/docs/public/code.css b/examples/docs/src/styles/code.css similarity index 61% rename from examples/docs/public/code.css rename to examples/docs/src/styles/code.css index 3fbb26626..312c45ef2 100644 --- a/examples/docs/public/code.css +++ b/examples/docs/src/styles/code.css @@ -1,3 +1,52 @@ +/* General */ +pre { + background-color: var(--theme-code-bg); + color: var(--theme-code-text); +} +code { + font-family: var(--font-mono); + font-size: 0.85em; +} +blockquote code:not([class*='language']) { + background-color: var(--theme-bg); +} + +@media (min-width: 37.75em) { + pre { + --padding-inline: 1.25rem; + border-radius: 8px; + margin-left: 0; + margin-right: 0; + } +} + +code:not([class*='language']) { + --border-radius: 3px; + --padding-block: 0.2rem; + --padding-inline: 0.4rem; + color: var(--theme-code-inline-text); + background-color: var(--theme-code-inline-bg); + padding: var(--padding-block) var(--padding-inline); + margin: calc(var(--padding-block) * -1) -0.125em; + border-radius: var(--border-radius); + box-shadow: 0 2px 1px 0 rgba(0, 0, 0, 0.08); +} + +pre > code:not([class*='language']) { + background-color: transparent; + padding: 0; + margin: 0; + border-radius: 0; + color: inherit; +} + +pre > code { + font-size: 1em; +} + + + +/* Syntax Highlighting */ .language-css > code, .language-sass > code, .language-scss > code { diff --git a/examples/docs/src/styles/index.css b/examples/docs/src/styles/index.css new file mode 100644 index 000000000..fc393e30c --- /dev/null +++ b/examples/docs/src/styles/index.css @@ -0,0 +1,4 @@ +@import './theme.css'; +@import './base.css'; +@import './typography.css'; +@import './code.css'; \ No newline at end of file diff --git a/examples/docs/public/theme.css b/examples/docs/src/styles/theme.css similarity index 100% rename from examples/docs/public/theme.css rename to examples/docs/src/styles/theme.css diff --git a/examples/docs/src/styles/typography.css b/examples/docs/src/styles/typography.css new file mode 100644 index 000000000..e858af846 --- /dev/null +++ b/examples/docs/src/styles/typography.css @@ -0,0 +1,99 @@ + +/* Typography */ +h1, +h2, +h3, +h4, +h5, +h6 { + margin-bottom: 1rem; + font-weight: bold; + line-height: 1; +} + +h1, +h2 { + max-width: 40ch; +} + +:is(h2, h3):not(:first-child) { + margin-top: 3rem; +} + +:is(h4, h5, h6):not(:first-child) { + margin-top: 2rem; +} + +h1 { + font-size: 3.25rem; + font-weight: 800; +} + +h2 { + font-size: 2.5rem; +} + +h3 { + font-size: 1.75rem; +} + +h4 { + font-size: 1.3rem; +} + +h5 { + font-size: 1rem; +} + +p { + line-height: 1.65em; + color: var(--theme-text-light); +} + +small, +.text_small { + font-size: 0.833rem; +} + +a { + color: var(--theme-text-accent); + font-weight: 400; + text-underline-offset: 0.08em; + align-items: center; + gap: 0.5rem; +} + +a > code:not([class*='language']) { + position: relative; + color: var(--theme-text-accent); + background: transparent; + text-underline-offset: var(--padding-block); +} + +a > code:not([class*='language'])::before { + content: ''; + position: absolute; + top: 0; + right: 0; + bottom: 0; + left: 0; + display: block; + background: var(--theme-accent); + opacity: var(--theme-accent-opacity); + border-radius: var(--border-radius); +} + +a:hover, +a:focus { + text-decoration: underline; +} + +a:focus { + outline: 2px solid currentColor; + outline-offset: 0.25em; +} + +strong { + font-weight: 600; + color: inherit; +} diff --git a/package.json b/package.json index bc8ac614b..a30ec1c2d 100644 --- a/package.json +++ b/package.json @@ -24,6 +24,7 @@ }, "workspaces": [ "packages/renderers/*", + "packages/components/*", "packages/*", "examples/*", "scripts", diff --git a/packages/components/docs/README.md b/packages/components/docs/README.md new file mode 100644 index 000000000..a07579bcc --- /dev/null +++ b/packages/components/docs/README.md @@ -0,0 +1,105 @@ +# `@astrojs/docs` - Astro Components Kit + +``` +npm install @astrojs/docs +``` + +This package is the component library that powers the Astro `docs` starter template. + +This is only a collection of components. **If you are looking for an already-themed, batteries-included template for your next project, check out the `docs` starter kit via `npm init astro` instead.** + +## What is in this package? + +This package contains several common UI components for documentation websites, including an i18n language selector and an Algolia-powered search bar. + +This package also includes a CSS Grid layout for your site, using a left sidebar for page navigation and a right sidebar for section navigation within each page. The design is responsive to work across desktop and mobile. + +## How to Use This Package + +Because `@astrojs/docs` is a lower-level UI library, you will need to write some code on your end to integrate it. The best way to do that is with a [Page Layout](https://docs.astro.build/core-concepts/layouts) component, like the example below: + +```astro +--- +// Example: src/layouts/MainLayout.astro +// +// - The main layout for your docs site. +// This includes all reusable UI from the '@astrojs/docs' package. +// Markdown content will be injected at the `` component. +// +// To use this layout: set the `layout` in your markdown page's frontmatter. +// +// The fastest way to customize your layout is to add new components +// to any existing layout "slot". For example, `` is a custom +// component that lives in this project "src/components" directory. +// +// You can also completely replace layout components like `LeftSidebar` +// and `PageContent` with your own UI. + +import {PageLayout, Header, PageContent, LeftSidebar, RightSidebar} from '@astrojs/docs'; +import Head from '../components/Head.astro'; +import * as CONFIG from '../config.ts'; + +const { content = {} } = Astro.props; +const dir = content.dir || CONFIG.SITE.dir; +const lang = content.lang || CONFIG.SITE.lang; +const currentPage = Astro.request.url.pathname; +const currentFile = `src/pages${currentPage.replace(/\/$/, "")}.md`; +const editUrlWithFile = CONFIG.EDIT_URL && (CONFIG.EDIT_URL + currentFile); +--- + + +
+ + + + + + +``` + +You can customize any section of the page layout by replacing these components with components of your own. Replacing `` with ``, for example, will place your `` component in the left sidebar section of the page layout. Many components can share the same slot, if you'd like to add new UI without removing existing. + +You can control the document `` using the `slot="head"` slot. By default, no elements are added to the page head for you. We recommend placing all `` elements into one (or more) `src/components/Head.astro` component(s) in your project. + +See the `` documentation below for a list of all supported slots. +## Components +### All Layout Components + +These components control full pieces of the docs page layout, including sidebars and headers. `` controls the CSS Grid layout, while the rest control the UI that ends up in each area of the grid. You can use all of them together, or mix-and-match different UI inside of ``. + +```js +import { + // The full page layout. See supported slots in the example above. + PageLayout, + // Individual parts of the default page layout. + Header, + LeftSidebar, + RightSidebar, + PageContent, +} from '@astrojs/docs'; +``` + +### All Static UI Components + +These components are static and require zero JavaScript to run. + +```js +import { + AstroLogo, + AvatarList, + SkipToContent, +} from '@astrojs/docs'; +``` +### All Dynamic UI Components + +These components may require JavaScript to run. You can include JavaScript automatically by using them with `client:*` directives. Check out Astro's documentation on [Partial Hydration](https://docs.astro.build/core-concepts/component-hydration) for more information. + +```js +import { + LanguageSelect, + Search, + SidebarToggle, + ThemeToggle, + TableOfContents, +} from '@astrojs/docs'; +``` \ No newline at end of file diff --git a/packages/components/docs/astro.config.mjs b/packages/components/docs/astro.config.mjs new file mode 100644 index 000000000..120106f3e --- /dev/null +++ b/packages/components/docs/astro.config.mjs @@ -0,0 +1,17 @@ +// Full Astro Configuration API Documentation: +// https://docs.astro.build/reference/configuration-reference + +// @type-check enabled! +// VSCode and other TypeScript-enabled text editors will provide auto-completion, +// helpful tooltips, and warnings if your exported object is invalid. +// You can disable this by removing "@ts-check" and `@type` comments below. + +// @ts-check +export default /** @type {import('astro').AstroUserConfig} */ ({ + renderers: [ + // Enable the Preact renderer to support Preact JSX components. + '@astrojs/renderer-preact', + // Enable the React renderer, for the Algolia search component + '@astrojs/renderer-react', + ], +}); diff --git a/packages/components/docs/package.json b/packages/components/docs/package.json new file mode 100644 index 000000000..96cb66a2f --- /dev/null +++ b/packages/components/docs/package.json @@ -0,0 +1,21 @@ +{ + "name": "@astrojs/docs", + "version": "0.0.1", + "scripts": { + "dev": "astro dev", + "start": "astro dev", + "build": "astro build", + "preview": "astro preview" + }, + "main": "./src/index.js", + "type": "module", + "dependencies": { + "@docsearch/react": "^1.0.0-alpha.27" + }, + "devDependencies": { + "astro": "^0.20.3" + }, + "snowpack": { + "workspaceRoot": "../../.." + } +} diff --git a/examples/docs/src/components/Header/Header.astro b/packages/components/docs/src/PageLayout/Header.astro similarity index 78% rename from examples/docs/src/components/Header/Header.astro rename to packages/components/docs/src/PageLayout/Header.astro index a50957240..1c64f6c67 100644 --- a/examples/docs/src/components/Header/Header.astro +++ b/packages/components/docs/src/PageLayout/Header.astro @@ -1,14 +1,10 @@ --- -import { getLanguageFromURL, KNOWN_LANGUAGE_CODES } from '../../languages.ts'; -import * as CONFIG from '../../config.ts'; -import AstroLogo from './AstroLogo.astro'; -import SkipToContent from './SkipToContent.astro'; -import SidebarToggle from './SidebarToggle.tsx'; -import LanguageSelect from './LanguageSelect.jsx'; -import Search from "./Search.jsx"; - -const {currentPage} = Astro.props; -const lang = currentPage && getLanguageFromURL(currentPage); +import AstroLogo from '../components/AstroLogo.astro'; +import SkipToContent from '../components/SkipToContent.astro'; +import SidebarToggle from '../components/SidebarToggle.js'; +import LanguageSelect from '../components/LanguageSelect.js'; +import Search from '../components/Search.js'; +const {currentPage, lang, languages, search} = Astro.props; --- + +
+
+

{title}

+ + +
+
\ No newline at end of file diff --git a/packages/components/docs/src/PageLayout/PageLayout.astro b/packages/components/docs/src/PageLayout/PageLayout.astro new file mode 100644 index 000000000..03f79cd83 --- /dev/null +++ b/packages/components/docs/src/PageLayout/PageLayout.astro @@ -0,0 +1,115 @@ +--- +const { dir, lang } = Astro.props; +--- + + + + + + + + + +
+ +
+ +
+ +
+ + + + + diff --git a/packages/components/docs/src/PageLayout/RightSidebar.astro b/packages/components/docs/src/PageLayout/RightSidebar.astro new file mode 100644 index 000000000..898a9ea40 --- /dev/null +++ b/packages/components/docs/src/PageLayout/RightSidebar.astro @@ -0,0 +1,34 @@ +--- +import TableOfContents from '../components/TableOfContents.jsx'; +import MoreMenu from '../components/MoreMenu.astro'; +const {content, editUrl, inviteUrl} = Astro.props; +--- + + \ No newline at end of file diff --git a/examples/docs/src/components/Header/AstroLogo.astro b/packages/components/docs/src/components/AstroLogo.astro similarity index 100% rename from examples/docs/src/components/Header/AstroLogo.astro rename to packages/components/docs/src/components/AstroLogo.astro diff --git a/examples/docs/src/components/Footer/AvatarList.astro b/packages/components/docs/src/components/AvatarList.astro similarity index 92% rename from examples/docs/src/components/Footer/AvatarList.astro rename to packages/components/docs/src/components/AvatarList.astro index 589e296b9..599f01982 100644 --- a/examples/docs/src/components/Footer/AvatarList.astro +++ b/packages/components/docs/src/components/AvatarList.astro @@ -1,8 +1,7 @@ --- // fetch all commits for just this page's path -const path = "docs/" + Astro.props.path; -const url = `https://api.github.com/repos/snowpackjs/astro/commits?path=${path}`; -const commitsURL = `https://github.com/snowpackjs/astro/commits/main/${path}`; +const url = `https://api.github.com/repos/${Astro.props.repo}/commits?path=${Astro.props.file}`; +const commitsURL = `https://github.com/${Astro.props.repo}/commits/${Astro.props.branch || 'main'}/${Astro.props.file}`; async function getCommits(url) { try { @@ -34,8 +33,7 @@ async function getCommits(url) { return data; } catch (e) { - console.warn(`[error] /src/components/AvatarList.astro - ${e?.message ?? e}`); + console.warn(`[error] AvatarList: ${e && e.message || e}`); return new Array(); } } diff --git a/examples/docs/src/components/Header/LanguageSelect.css b/packages/components/docs/src/components/LanguageSelect.css similarity index 100% rename from examples/docs/src/components/Header/LanguageSelect.css rename to packages/components/docs/src/components/LanguageSelect.css diff --git a/examples/docs/src/components/Header/LanguageSelect.tsx b/packages/components/docs/src/components/LanguageSelect.tsx similarity index 70% rename from examples/docs/src/components/Header/LanguageSelect.tsx rename to packages/components/docs/src/components/LanguageSelect.tsx index 8b9807fe8..20cdf49de 100644 --- a/examples/docs/src/components/Header/LanguageSelect.tsx +++ b/packages/components/docs/src/components/LanguageSelect.tsx @@ -1,9 +1,8 @@ -import type { FunctionalComponent } from 'preact'; import { h } from 'preact'; +import type { FunctionalComponent } from 'preact'; import './LanguageSelect.css'; -import { KNOWN_LANGUAGES, langPathRegex } from '../../languages'; -const LanguageSelect: FunctionalComponent<{ lang: string }> = ({ lang }) => { +const LanguageSelect: FunctionalComponent<{ lang: string, options: Record }> = ({ lang, options }) => { return (
{key} ); diff --git a/examples/docs/src/components/RightSidebar/MoreMenu.astro b/packages/components/docs/src/components/MoreMenu.astro similarity index 83% rename from examples/docs/src/components/RightSidebar/MoreMenu.astro rename to packages/components/docs/src/components/MoreMenu.astro index c23da0c7b..81f84fd26 100644 --- a/examples/docs/src/components/RightSidebar/MoreMenu.astro +++ b/packages/components/docs/src/components/MoreMenu.astro @@ -1,8 +1,7 @@ --- -import ThemeToggleButton from './ThemeToggleButton.jsx'; -import * as CONFIG from '../../config.js'; -const {editHref} = Astro.props; -const showMoreSection = (CONFIG.COMMUNITY_INVITE_URL || editHref); +import ThemeToggle from './ThemeToggle.astro'; +const {editUrl, inviteUrl} = Astro.props; +const showMoreSection = (inviteUrl || editUrl); --- {showMoreSection &&

More

}