From 166e22bdf35b9751dc42f5cc6cb27a99b077df93 Mon Sep 17 00:00:00 2001 From: "Fred K. Schott" Date: Thu, 15 Jul 2021 14:13:35 -0400 Subject: merge in docs site (#705) --- docs/src/components/ArticleFooter.astro | 16 + docs/src/components/AstroLogo.astro | 20 + docs/src/components/AvatarList.astro | 151 ++++++ docs/src/components/DocSidebar.tsx | 65 +++ docs/src/components/EditOnGithub.tsx | 25 + docs/src/components/MenuToggle.tsx | 44 ++ docs/src/components/Note.astro | 48 ++ docs/src/components/SiteSidebar.astro | 69 +++ docs/src/components/ThemeToggle.tsx | 97 ++++ docs/src/config.ts | 67 +++ docs/src/layouts/Main.astro | 248 ++++++++++ docs/src/pages/blog/island-architecture.md | 240 ++++++++++ docs/src/pages/core-concepts/astro-components.md | 355 ++++++++++++++ docs/src/pages/core-concepts/astro-pages.md | 60 +++ docs/src/pages/core-concepts/collections.md | 211 +++++++++ .../src/pages/core-concepts/component-hydration.md | 91 ++++ docs/src/pages/core-concepts/layouts.md | 155 +++++++ docs/src/pages/core-concepts/project-structure.md | 56 +++ docs/src/pages/examples.md | 8 + docs/src/pages/guides/data-fetching.md | 64 +++ docs/src/pages/guides/deploy.md | 256 +++++++++++ docs/src/pages/guides/imports.md | 139 ++++++ docs/src/pages/guides/markdown-content.md | 222 +++++++++ docs/src/pages/guides/publish-to-npm.md | 83 ++++ docs/src/pages/guides/styling.md | 511 +++++++++++++++++++++ docs/src/pages/index.astro | 251 ++++++++++ docs/src/pages/installation.md | 92 ++++ docs/src/pages/integrations/data-sources-cms.md | 4 + docs/src/pages/integrations/deploy-astro.md | 4 + docs/src/pages/integrations/developer-tools.md | 4 + docs/src/pages/integrations/state-management.md | 4 + .../pages/integrations/styles-and-css-libraries.md | 4 + docs/src/pages/quick-start.md | 50 ++ docs/src/pages/reference/api-reference.md | 179 ++++++++ docs/src/pages/reference/builtin-components.md | 32 ++ docs/src/pages/reference/cli-reference.md | 58 +++ .../src/pages/reference/configuration-reference.md | 30 ++ docs/src/pages/reference/renderer-reference.md | 158 +++++++ 38 files changed, 4171 insertions(+) create mode 100644 docs/src/components/ArticleFooter.astro create mode 100644 docs/src/components/AstroLogo.astro create mode 100644 docs/src/components/AvatarList.astro create mode 100644 docs/src/components/DocSidebar.tsx create mode 100644 docs/src/components/EditOnGithub.tsx create mode 100644 docs/src/components/MenuToggle.tsx create mode 100644 docs/src/components/Note.astro create mode 100644 docs/src/components/SiteSidebar.astro create mode 100644 docs/src/components/ThemeToggle.tsx create mode 100644 docs/src/config.ts create mode 100644 docs/src/layouts/Main.astro create mode 100644 docs/src/pages/blog/island-architecture.md create mode 100644 docs/src/pages/core-concepts/astro-components.md create mode 100644 docs/src/pages/core-concepts/astro-pages.md create mode 100644 docs/src/pages/core-concepts/collections.md create mode 100644 docs/src/pages/core-concepts/component-hydration.md create mode 100644 docs/src/pages/core-concepts/layouts.md create mode 100644 docs/src/pages/core-concepts/project-structure.md create mode 100644 docs/src/pages/examples.md create mode 100644 docs/src/pages/guides/data-fetching.md create mode 100644 docs/src/pages/guides/deploy.md create mode 100644 docs/src/pages/guides/imports.md create mode 100644 docs/src/pages/guides/markdown-content.md create mode 100644 docs/src/pages/guides/publish-to-npm.md create mode 100644 docs/src/pages/guides/styling.md create mode 100644 docs/src/pages/index.astro create mode 100644 docs/src/pages/installation.md create mode 100644 docs/src/pages/integrations/data-sources-cms.md create mode 100644 docs/src/pages/integrations/deploy-astro.md create mode 100644 docs/src/pages/integrations/developer-tools.md create mode 100644 docs/src/pages/integrations/state-management.md create mode 100644 docs/src/pages/integrations/styles-and-css-libraries.md create mode 100644 docs/src/pages/quick-start.md create mode 100644 docs/src/pages/reference/api-reference.md create mode 100644 docs/src/pages/reference/builtin-components.md create mode 100644 docs/src/pages/reference/cli-reference.md create mode 100644 docs/src/pages/reference/configuration-reference.md create mode 100644 docs/src/pages/reference/renderer-reference.md (limited to 'docs/src') diff --git a/docs/src/components/ArticleFooter.astro b/docs/src/components/ArticleFooter.astro new file mode 100644 index 000000000..48de51054 --- /dev/null +++ b/docs/src/components/ArticleFooter.astro @@ -0,0 +1,16 @@ +--- +import AvatarList from './AvatarList.astro'; +const { path } = Astro.props; +--- + + + + diff --git a/docs/src/components/AstroLogo.astro b/docs/src/components/AstroLogo.astro new file mode 100644 index 000000000..ff1939ad9 --- /dev/null +++ b/docs/src/components/AstroLogo.astro @@ -0,0 +1,20 @@ +--- +const {size} = Astro.props; +--- + \ No newline at end of file diff --git a/docs/src/components/AvatarList.astro b/docs/src/components/AvatarList.astro new file mode 100644 index 000000000..09fc089b9 --- /dev/null +++ b/docs/src/components/AvatarList.astro @@ -0,0 +1,151 @@ +--- +// fetch all commits for just this page's path +const { path } = Astro.props; +const url = `https://api.github.com/repos/snowpackjs/astro-docs/commits?path=${path}`; +const commitsURL = `https://github.com/snowpackjs/astro-docs/commits/main/${path}`; + +async function getCommits(url) { + try { + const token = import.meta.env.SNOWPACK_PUBLIC_GITHUB_TOKEN; + if (!token) { + throw new Error( + 'Cannot find "SNOWPACK_PUBLIC_GITHUB_TOKEN" used for escaping rate-limiting.' + ); + } + + const auth = `Basic ${Buffer.from(token, "binary").toString("base64")}`; + + const res = await fetch(url, { + method: "GET", + headers: { + Authorization: auth, + "User-Agent": "astro-docs/1.0", + }, + }); + + const data = await res.json(); + + if (!res.ok) { + throw new Error( + `Request to fetch commits failed. Reason: ${res.statusText} + Message: ${data.message}` + ); + } + + return data; + } catch (e) { + console.warn(`[error] /src/components/AvatarList.astro + ${e?.message ?? e}`); + return new Array(); + } +} + +function removeDups(arr) { + if (!arr) { + return new Array(); + } + let map = new Map(); + + for (let item of arr) { + let author = item.author; + // Deduplicate based on author.id + map.set(author.id, { login: author.login, id: author.id }); + } + + return Array.from(map.values()); +} + +const data = await getCommits(url); +const unique = removeDups(data); +const recentContributors = unique.slice(0, 3); // only show avatars for the 3 most recent contributors +const additionalContributors = unique.length - recentContributors.length; // list the rest of them as # of extra contributors + +--- + +
+ + {additionalContributors > 0 && {`and ${additionalContributors} additional contributor${additionalContributors > 1 ? 's' : ''}.`}} + {unique.length === 0 && Contributors} +
+ + diff --git a/docs/src/components/DocSidebar.tsx b/docs/src/components/DocSidebar.tsx new file mode 100644 index 000000000..24e9dc4d9 --- /dev/null +++ b/docs/src/components/DocSidebar.tsx @@ -0,0 +1,65 @@ +import type { FunctionalComponent } from 'preact'; +import { h } from 'preact'; +import { useState, useEffect, useRef } from 'preact/hooks'; +import EditOnGithub from './EditOnGithub'; + +const DocSidebar: FunctionalComponent<{ headers: any[]; editHref: string }> = ({ + headers = [], + editHref, +}) => { + const itemOffsets = useRef([]); + const [activeId, setActiveId] = useState(undefined); + + useEffect(() => { + const getItemOffsets = () => { + const titles = document.querySelectorAll('article :is(h1, h2, h3, h4)'); + itemOffsets.current = Array.from(titles).map((title) => ({ + id: title.id, + topOffset: title.getBoundingClientRect().top + window.scrollY, + })); + }; + + getItemOffsets(); + window.addEventListener('resize', getItemOffsets); + + return () => { + window.removeEventListener('resize', getItemOffsets); + }; + }, []); + + return ( + + ); +}; + +export default DocSidebar; diff --git a/docs/src/components/EditOnGithub.tsx b/docs/src/components/EditOnGithub.tsx new file mode 100644 index 000000000..5ff74e364 --- /dev/null +++ b/docs/src/components/EditOnGithub.tsx @@ -0,0 +1,25 @@ +import type { FunctionalComponent } from 'preact'; +import { h } from 'preact'; + +const EditOnGithub: FunctionalComponent<{ href: string }> = ({ href }) => { + return ( + + + + + + + Edit on GitHub + + ); +}; + +export default EditOnGithub; diff --git a/docs/src/components/MenuToggle.tsx b/docs/src/components/MenuToggle.tsx new file mode 100644 index 000000000..605581077 --- /dev/null +++ b/docs/src/components/MenuToggle.tsx @@ -0,0 +1,44 @@ +import type { FunctionalComponent } from 'preact'; +import { h, Fragment } from 'preact'; +import { useState, useEffect } from 'preact/hooks'; + +const MenuToggle: FunctionalComponent = () => { + const [sidebarShown, setSidebarShown] = useState(false); + + useEffect(() => { + const body = document.getElementsByTagName('body')[0]; + if (sidebarShown) { + body.classList.add('mobile-sidebar-toggle'); + } else { + body.classList.remove('mobile-sidebar-toggle'); + } + }, [sidebarShown]); + + return ( + + ); +}; + +export default MenuToggle; diff --git a/docs/src/components/Note.astro b/docs/src/components/Note.astro new file mode 100644 index 000000000..c3ae29cb4 --- /dev/null +++ b/docs/src/components/Note.astro @@ -0,0 +1,48 @@ +--- +const { type = 'tip', title } = Astro.props; +--- + + + + diff --git a/docs/src/components/SiteSidebar.astro b/docs/src/components/SiteSidebar.astro new file mode 100644 index 000000000..6d003d71d --- /dev/null +++ b/docs/src/components/SiteSidebar.astro @@ -0,0 +1,69 @@ +--- +import { sidebar } from '../config.ts'; +const {currentPage} = Astro.props; +--- + + + + + \ No newline at end of file diff --git a/docs/src/components/ThemeToggle.tsx b/docs/src/components/ThemeToggle.tsx new file mode 100644 index 000000000..31ab5ea74 --- /dev/null +++ b/docs/src/components/ThemeToggle.tsx @@ -0,0 +1,97 @@ +import type { FunctionalComponent } from 'preact'; +import { h, Fragment } from 'preact'; +import { useState, useEffect } from 'preact/hooks'; + +const themes = ['system', 'light', 'dark']; + +const icons = [ + + + , + + + , + + + , +]; + +const ThemeToggle: FunctionalComponent = () => { + const [theme, setTheme] = useState(themes[0]); + + useEffect(() => { + const user = localStorage.getItem('theme'); + if (!user) return; + setTheme(user); + }, []); + + useEffect(() => { + const root = document.documentElement; + if (theme === 'system') { + localStorage.removeItem('theme'); + if (window.matchMedia('(prefers-color-scheme: dark)').matches) { + root.classList.add('theme-dark'); + } else { + root.classList.remove('theme-dark'); + } + } else { + localStorage.setItem('theme', theme); + if (theme === 'light') { + root.classList.remove('theme-dark'); + } else { + root.classList.add('theme-dark'); + } + } + }, [theme]); + + return ( +
+ {themes.map((t, i) => { + const icon = icons[i]; + const checked = t === theme; + return ( + + ); + })} +
+ ); +}; + +export default ThemeToggle; diff --git a/docs/src/config.ts b/docs/src/config.ts new file mode 100644 index 000000000..bb96ac4e9 --- /dev/null +++ b/docs/src/config.ts @@ -0,0 +1,67 @@ +export const sidebar = [ + { + text: 'Setup', + link: '', + children: [ + { text: 'Installation', link: 'installation' }, + { text: 'Quickstart', link: 'quick-start' }, + { text: 'Examples', link: 'examples' }, + ], + }, + { + text: 'Basics', + link: 'core-concepts', + children: [ + { text: 'Project Structure', link: 'core-concepts/project-structure' }, + { text: 'Components', link: 'core-concepts/astro-components' }, + { text: 'Pages', link: 'core-concepts/astro-pages' }, + { text: 'Layouts', link: 'core-concepts/layouts' }, + { text: 'Collections', link: 'core-concepts/collections' }, + { text: 'Partial Hydration', link: 'core-concepts/component-hydration' }, + ], + }, + { + text: 'Guides', + link: 'guides', + children: [ + { text: 'Styling & CSS', link: 'guides/styling' }, + { text: 'Data Fetching', link: 'guides/data-fetching' }, + { text: 'Markdown', link: 'guides/markdown-content' }, + { text: 'Supported Imports', link: 'guides/imports' }, + // To be written when https://github.com/snowpackjs/astro/issues/501 is completed + // { text: 'Pagination', link: 'guides/pagination' }, + { text: 'Deploy a Website', link: 'guides/deploy' }, + { text: 'Publish a Component', link: 'guides/publish-to-npm' }, + ], + }, + { + text: 'Reference', + link: 'reference', + children: [ + { text: 'Built-In Components', link: 'reference/builtin-components' }, + { text: 'API Reference', link: 'reference/api-reference' }, + { text: 'CLI Reference', link: 'reference/cli-reference' }, + { + text: 'Configuration Reference', + link: 'reference/configuration-reference', + }, + { text: 'Renderer Reference', link: 'reference/renderer-reference' }, + ], + }, + // To add once rest of the site is complete + // see https://github.com/snowpackjs/astro-docs/issues/9 + // { + // text: 'Integrations', + // link: 'integrations', + // children: [ + // { text: 'Deploy Astro', link: 'integrations/deploy-astro' }, + // { text: 'Data Sources / CMS', link: 'integrations/data-sources-cms' }, + // { text: 'State Management', link: 'integrations/state-management' }, + // { + // text: 'Styles & CSS Libraries', + // link: 'integrations/styles-and-css-libraries', + // }, + // { text: 'Developer Tools', link: 'integrations/developer-tools' }, + // ], + // }, +]; diff --git a/docs/src/layouts/Main.astro b/docs/src/layouts/Main.astro new file mode 100644 index 000000000..3b98d88b6 --- /dev/null +++ b/docs/src/layouts/Main.astro @@ -0,0 +1,248 @@ +--- +import ArticleFooter from '../components/ArticleFooter.astro'; +import SiteSidebar from '../components/SiteSidebar.astro'; +import ThemeToggle from '../components/ThemeToggle.tsx'; +import DocSidebar from '../components/DocSidebar.tsx'; +import MenuToggle from '../components/MenuToggle.tsx'; + +const { content } = Astro.props; +const headers = content?.astro?.headers; +const currentPage = Astro.request.url.pathname; +const currentFile = currentPage === '/' ? 'src/pages/index.md' : `src/pages${currentPage.replace(/\/$/, "")}.md`; +const githubEditUrl = `https://github.com/snowpackjs/astro-docs/blob/main/${currentFile}`; +--- + + + + + + {content.title} + + + + +