Skip to content

Latest commit

 

History

History
136 lines (96 loc) · 4.32 KB

README.md

File metadata and controls

136 lines (96 loc) · 4.32 KB
Raw

Vidstack Site

This is the main Vidstack site and docs hosted at vidstack.io. The site is built with Astro, see their docs to get familiar with the framework.

Quickstart

  1. Install PNPM.
  2. Clone repository: git clone [email protected]:vidstack/site.git vidstack-site --depth=1
  3. Change directories and install dependencies: cd vidstack-site && pnpm i
  4. Run development server: npm run dev

Writing Docs

All documentation files can be found at src/content/docs. They're written using MDX which is automatically supported by Astro.

Sidebar Items

All pages that should be displayed in the docs sidebar need to be added to the docs sidebar items file.

Frameworks Filter

You can filter content by framework by adding a special subdirectory (wc/ or react/) at any path inside src/content/docs. For example:

  • src/content/docs/api/page.mdx: This page will load when either the current JS library selection is Web Components or React and available at the URL /docs/api/page and /docs/wc/api/page.

  • src/content/docs/api/wc/page.mdx: This page will load if the current JS library selection is "Web Components" and available at the URL /docs/wc/api/page.

  • src/content/docs/api/react/page.mdx: This page will load if the current JS library selection is "React" and available at the URL /docs/api/page.

MDX Directives

The following directives are included to help with writing docs in MDX files:

:::info
This is a helpful info callout! The following callout types are supported: note, info, tip,
warning, danger, experimental.
:::

:::yes
Tell the user they should do this!
:::

:::no
Tell the user they should _not_ do this!
:::

Code Snippets

All code snippets can be found at src/snippets. Vidstack supports light/dark code themes and multiple frameworks with more to come, hence writing multiple code fences in a file won't work as pages will bloat. Therefore, lazy loaded code snippets are used which we've documented how to create and use below.

Code Snippet ID

The relative path from src/snippets without the file extension is the snippet ID. For example, src/snippets/docs/main.ts has the snippet ID docs/main. The ID can be used to lazy load the snippet via the ::code directive in an MDX file like so:

// Lazy load code snippet at `src/snippets/docs/main.ts`
::code[docs/main]

// Accepts following options
::code[docs/main]{title="Main Page" numbers=true copy=true flat=true highlights="1-3,5-8"}

You will need to provide the file extension if there are two snippets with the same name:

::code[docs/main.ts]
::code[docs/main.css]

Relative Code Snippet ID

The snippet ID can be relative to the current URL path. For example, if you'd like to display a snippet at the URL path /docs/player/installation, then a code file can be placed at src/snippets/docs/player/installation/foo.css and loaded using the ::code directive like so:

// Loads the snippet with ID foo relative to current URL
::code[./foo]

// You can also walk up a directory from current URL
::code[../bar/foo]

// With extension
::code[../bar/foo.css]

Code Snippet Framework Filter

Similar to content framework filters, snippets can be placed inside special framework subdirectories (wc/ and react/) at any path inside src/snippets to be displayed when the JS library selection is matched.

For example, src/snippets/docs/player/installation/wc/foo and src/snippets/docs/player/installation/react/foo will both map to the snippet ID docs/player/installation/foo and be selected based on the current JS library selection.

Code Snippet Highlighting

Option one is to include it as part of the ::code directive options:

// Highlight lines 1-3 and 5-8
::code[some/id]{highlights="1-3,5-8"}

Option two is to include highlight comment markers in the code snippet file like so:

import { foo } from 'bar';

// @hl-start
const a = 1;
// @hl-end