···11export { DocsSidebar } from './DocsSidebar'
22export { DocsNav } from './DocsNav'
33export { Table } from './Table'
44+export { LinkCard } from './LinkCard'
55+export { StandardSite } from './StandardSite'
66+export { MarkdownButton } from './MarkdownButton'
77+export { ClickableHeading } from './ClickableHeading'
+3-3
app/components/sections/DefinitionsSection.tsx
···3838 </h2>
39394040 <p className="text-base sm:text-xl leading-snug tracking-tight text-muted">
4141- We currently define two main lexicons that cover the core building
4242- blocks of long-form platforms: where content lives, and what it
4343- contains.
4141+ We currently define three main lexicons that cover the core building
4242+ blocks of long-form platforms: where content lives, what it
4343+ contains, and how users connect with publications.
4444 </p>
45454646 <TabbedLexiconViewer tabs={ tabs } allSchemas={ allSchemas } />
···11+import { StandardSite } from '@/app/components/docs'
22+13# Frequently Asked Questions
2433-Common questions about Standard.site and implementing the lexicons.
55+Common questions about <StandardSite /> and implementing the lexicons.
4657## General
6879### What is Standard.site?
81099-Standard.site is a community-driven initiative to create shared lexicon schemas for long-form publishing on AT Protocol. It enables interoperability between different publishing platforms.
1111+<StandardSite /> is a community-driven initiative to create shared lexicon schemas for long-form publishing on AT Protocol. It enables interoperability between different publishing platforms.
10121113### Who created Standard.site?
12141313-Standard.site emerged from conversations between developers building long-form platforms on AT Protocol. It's maintained by the community and grows as builders identify shared needs.
1414-1515-### Is Standard.site official?
1616-1717-Standard.site is a community standard, not an official Bluesky or AT Protocol specification. However, it's designed to work seamlessly with the AT Protocol ecosystem.
1515+<StandardSite /> emerged from conversations between developers building long-form platforms on AT Protocol. It's maintained by the community and grows as builders identify shared needs.
18161917## Technical
20182119### Do I need to use all the lexicons?
22202323-No. You can implement just the lexicons that make sense for your application. The schemas are designed to work independently while supporting richer integrations when combined.
2121+No. Applications can implement just the lexicons that make sense for their use case. The schemas are designed to work independently while supporting richer integrations when combined.
24222523### Can I extend the schemas?
26242727-The standard focuses on shared metadata fields. You're free to add additional fields in your application, though they may not be understood by other platforms.
2828-2929-### How do I validate records?
3030-3131-Use AT Protocol's standard validation mechanisms. The lexicon schemas define the expected structure, and records are validated against these schemas by the PDS.
2525+The standard focuses on shared metadata properties. Applications are free to add additional properties, though they may not be understood by other platforms.
32263327## Contributing
34283529### How can I contribute?
36303737-Standard.site is developed in the open. Join the conversation on Bluesky, Tangled, or check the project on GitHub to propose changes or additions.
3131+<StandardSite /> is developed in the open. Join the conversation on Bluesky or [Tangled](https://tangled.org/standard.site) to propose changes or additions.
38323933### How are changes decided?
4034
+43
content/docs/implementations.mdx
···11+import { LinkCard } from '@/app/components/docs'
22+33+import { StandardSite } from '@/app/components/docs'
44+55+# Implementations
66+77+Projects and tools using <StandardSite /> lexicons to build interoperable platforms on AT Protocol.
88+99+## Development Tools
1010+1111+<LinkCard url="https://site-validator.fly.dev" />
1212+1313+## Migration Tools
1414+1515+<LinkCard url="https://sequoia.pub/blog/introducing-sequoia/" />
1616+1717+## Indexes & Discovery
1818+1919+<LinkCard url="https://read.pckt.blog" />
2020+2121+<LinkCard url="https://docs.surf" />
2222+2323+<LinkCard url="https://standard-search.octet-stream.net/" />
2424+2525+## Building Your Own
2626+2727+Building a tool or platform using <StandardSite /> lexicons? We'd love to hear about it! <StandardSite /> is a community-driven initiative, and new implementations help grow the ecosystem.
2828+2929+### What to Build
3030+3131+Some ideas for new implementations:
3232+3333+- **RSS bridges**: Convert <StandardSite /> records to RSS/Atom feeds
3434+- **Static site generators**: Export <StandardSite /> content to static HTML
3535+- **Mobile readers**: Native mobile apps for reading <StandardSite /> content
3636+- **Import tools**: Import content from existing platforms to <StandardSite />
3737+- **Content management**: Editors for creating <StandardSite /> records
3838+3939+## Related
4040+4141+- [Quick Start](/docs/quick-start) - Start implementing <StandardSite />
4242+- [Publication lexicon](/docs/lexicons/publication) - Understand publication schemas
4343+- [Document lexicon](/docs/lexicons/document) - Understand document schemas
+17-12
content/docs/introduction.mdx
···11+import { StandardSite } from '@/app/components/docs'
22+13# Introduction
2433-**Standard.site** provides shared lexicons for long-form publishing on AT Protocol.
55+<StandardSite /> lexicons bring long-form writing into the social web by linking blog posts and articles to the AT Protocol. This integration helps make published work easier to share and find, while ensuring authors maintain ownership of their writing in the form of records stored on their Personal Data Server (PDS).
4657## What is Standard.site?
6877-Standard.site is a set of lexicon schemas that enable interoperability between long-form publishing platforms built on AT Protocol. By using shared schemas, content created on one platform can be understood and displayed by any other compatible platform.
99+Our lexicons are built with discovery and connectivity in mind. <StandardSite /> lexicons bridge the gap between writers and the communities they intend to reach.
81099-## Why use shared lexicons?
1111+We have two main lexicons that are used to create and manage publications and written documents. In addition to these base lexicons, we maintain a handful of supporting lexicons for social features and utility.
10121111-- **Interoperability**: Your content works across multiple platforms
1212-- **Portability**: Move your content without losing structure
1313-- **Consistency**: Shared vocabulary for publications, documents, and subscriptions
1414-1515-## Core concepts
1313+## Core Lexicons
16141715### Publications
18161919-A publication is a container for documents. Think of it as a blog, magazine, or newsletter. Each publication has metadata like a title, description, and avatar.
1717+The [`site.standard.publication`](/docs/lexicons/publication) lexicon is a representation of a collection of documents published to the web. It includes important information about a publication including its location on the web, theming information, user preferences, and more.
20182119### Documents
22202323-Documents are individual pieces of content within a publication. They contain the actual written content, along with metadata like title, publish date, and status.
2121+The [`site.standard.document`](/docs/lexicons/document) lexicon provides metadata for individual documents. Including the document's relation to a publication if applicable, a path to the document, and more information like a document's complete contents.
24222523### Subscriptions
26242727-Subscriptions track relationships between users and publications, enabling follow functionality.
2525+The [`site.standard.graph.subscription`](/docs/lexicons/subscription) lexicon tracks relationships between users and publications, enabling follow functionality and personalized content feeds across the AT Protocol network.
2626+2727+## Design Philosophy
2828+2929+There are minimal requirements to use these lexicons, ensuring adoptability is as straightforward as possible. As long as the minimum required properties are included in published records, they will be available for other AT Protocol platforms to consume.
3030+3131+While <StandardSite /> lexicons are lightweight on their own, they can be expanded to fit individual needs if necessary. The existing properties should not be seen as constraints, but rather as starting points.
28322933## Next steps
30343135- Read the [Quick Start](/docs/quick-start) guide to begin implementing
3236- Explore the [Publication lexicon](/docs/lexicons/publication) schema
3333-- Check out the [FAQ](/docs/faq) for common questions
3737+- Learn about [Verification](/docs/verification) to link records to a domain
3838+- Check out [Implementations](/docs/implementations) to see tools and platforms using <StandardSite />
+47-32
content/docs/lexicons/document.mdx
···2233# Document Lexicon
4455-The `site.standard.document` lexicon defines the schema for documents within publications.
55+The `site.standard.document` lexicon provides metadata for documents published on the web.
6677## Overview
8899-A document represents an individual piece of content, such as a blog post or article. Documents belong to a publication and contain the actual written content along with metadata.
99+Documents may be standalone or associated with a publication. This lexicon can be used to store a document's content and its associated metadata.
10101111## Schema
12121313+### Required Properties
1414+1315<Table
1414- headers={['Field', 'Type', 'Required', 'Description']}
1616+ headers={['Property', 'Type', 'Description']}
1517 rows={[
1616- ['publication', 'at-uri', 'Yes', 'Reference to parent publication'],
1717- ['title', 'string', 'Yes', 'Document title'],
1818- ['content', 'string', 'Yes', 'The document content'],
1919- ['status', 'string', 'Yes', 'One of: draft, published, archived'],
2020- ['visibility', 'string', 'No', 'One of: public, subscribers, private'],
2121- ['createdAt', 'datetime', 'Yes', 'When the document was created'],
2222- ['publishedAt', 'datetime', 'No', 'When the document was published'],
1818+ ['site', 'string', 'Points to a publication record (at://) or publication URL (https://). Avoid trailing slashes.'],
1919+ ['title', 'string', 'Title of the document'],
2020+ ['publishedAt', 'datetime', 'Timestamp of the document\'s publish time'],
2321 ]}
2422/>
25232626-## Status values
2424+### Optional Properties
27252828-- **draft**: Work in progress, not publicly visible
2929-- **published**: Live and visible according to visibility settings
3030-- **archived**: No longer actively displayed but still accessible
2626+<Table
2727+ headers={['Property', 'Type', 'Description']}
2828+ rows={[
2929+ ['path', 'string', 'Combined with site/publication URL to construct canonical URL. Should start with a slash.'],
3030+ ['description', 'string', 'Brief description or excerpt from the document'],
3131+ ['coverImage', 'blob', 'Image for thumbnail or cover. Less than 1MB in size.'],
3232+ ['content', 'union', 'Open union used to define the record\'s content. Each entry must specify a $type.'],
3333+ ['textContent', 'string', 'Plaintext representation of the document. Should not contain markdown or formatting.'],
3434+ ['bskyPostRef', 'ref', 'Strong reference to a Bluesky post. Useful to track comments off-platform.'],
3535+ ['tags', 'array', 'Array of strings to tag or categorize the document. Avoid prepending with hashtags.'],
3636+ ['updatedAt', 'datetime', 'Timestamp of the document\'s last edit'],
3737+ ]}
3838+/>
31393240## Example
33413434-```typescript
3535-const document = {
3636- $type: 'site.standard.document',
3737- publication: 'at://did:plc:abc.../site.standard.publication/main',
3838- title: 'Getting Started with AT Protocol',
3939- content: '...', // Your content here
4040- status: 'published',
4141- visibility: 'public',
4242- createdAt: '2024-01-20T14:00:00.000Z',
4343- publishedAt: '2024-01-20T14:30:00.000Z',
4242+```json
4343+{
4444+ "$type": "site.standard.document",
4545+ "site": "at://did:plc:abc123/site.standard.publication/3lwafzkjqm25s",
4646+ "path": "/blog/getting-started",
4747+ "title": "Getting Started with Standard.site",
4848+ "description": "Learn how to use Standard.site lexicons in your project",
4949+ "coverImage": {
5050+ "$type": "blob",
5151+ "ref": {
5252+ "$link": "bafkreiexample123456789"
5353+ },
5454+ "mimeType": "image/jpeg",
5555+ "size": 245678
5656+ },
5757+ "textContent": "Full text of the article...",
5858+ "tags": ["tutorial", "atproto"],
5959+ "publishedAt": "2024-01-20T14:30:00.000Z"
4460}
4561```
46624747-## Content format
6363+## Content Format
48644949-The content field is intentionally flexible. Standard.site does not prescribe a specific content format, allowing platforms to use:
6565+The content property is an open union, allowing for extensibility. Each entry must specify a `$type` and may be extended with other lexicons to support additional content formats like Markdown, blocks, or other rich text.
50665151-- Markdown
5252-- HTML
5353-- JSON-based rich text
5454-- Custom formats
6767+## View the Lexicon
55685656-This flexibility enables each platform to optimize for their use case while maintaining interoperability at the metadata level.
6969+- [View full lexicon schema](https://pdsls.dev/at://did:plc:re3ebnp5v7ffagz6rb6xfei4/com.atproto.lexicon.schema/site.standard.document)
7070+- [Example record](https://pdsls.dev/at://did:plc:revjuqmkvrw6fnkxppqtszpv/site.standard.document/3mbfqhezge25u)
57715872## Related
59736060-- [Publication lexicon](/docs/lexicons/publication) - Parent container for documents
7474+- [Publication lexicon](/docs/lexicons/publication) - Collections of documents
7575+- [Verification](/docs/verification) - Link documents to web pages
6176- [Quick Start](/docs/quick-start) - Implementation guide
+78-14
content/docs/lexicons/publication.mdx
···2233# Publication Lexicon
4455-The `site.standard.publication` lexicon defines the schema for publications.
55+The `site.standard.publication` lexicon is used to describe information about a particular publication.
6677## Overview
8899-A publication represents a container for documents, similar to a blog, magazine, or newsletter. Each user can have multiple publications.
99+A publication represents a collection of documents published to the web. It includes important information about a publication including its location on the web, theming information, user preferences, and more.
1010+1111+The publication lexicon is not a requirement, but is recommended when publishing collections of related documents.
10121113## Schema
12141515+### Required Properties
1616+1317<Table
1414- headers={['Field', 'Type', 'Required', 'Description']}
1818+ headers={['Property', 'Type', 'Description']}
1519 rows={[
1616- ['title', 'string', 'Yes', 'The publication title'],
1717- ['description', 'string', 'No', 'A brief description'],
1818- ['avatar', 'blob', 'No', 'Publication avatar image'],
1919- ['createdAt', 'datetime', 'Yes', 'When the publication was created'],
2020+ ['url', 'string', 'Base URL for the publication (ex: https://standard.site). Combined with document path to construct full URLs. Avoid trailing slashes.'],
2121+ ['name', 'string', 'The name of the publication'],
2222+ ]}
2323+/>
2424+2525+### Optional Properties
2626+2727+<Table
2828+ headers={['Property', 'Type', 'Description']}
2929+ rows={[
3030+ ['icon', 'blob', 'Square image to identify publication'],
3131+ ['description', 'string', 'Description of the publication'],
3232+ ['basicTheme', 'ref', 'Simplified publication theme (ref → [site.standard.theme.basic](/docs/lexicons/theme))'],
3333+ ['preferences', 'object', 'Platform-specific preferences for the publication'],
3434+ ['preferences.showInDiscover', 'boolean', 'Whether the publication should appear in discovery feeds'],
2035 ]}
2136/>
22372338## Example
24392525-```typescript
2626-const publication = {
2727- $type: 'site.standard.publication',
2828- title: 'Tech Insights',
2929- description: 'Weekly thoughts on technology and software development',
3030- createdAt: '2024-01-15T10:30:00.000Z',
4040+```json
4141+{
4242+ "$type": "site.standard.publication",
4343+ "url": "https://standard.site",
4444+ "icon": {
4545+ "$type": "blob",
4646+ "ref": {
4747+ "$link": "bafkreiexample123456789"
4848+ },
4949+ "mimeType": "image/png",
5050+ "size": 12345
5151+ },
5252+ "name": "Standard.site Blog",
5353+ "description": "Documentation and updates about Standard.site lexicons",
5454+ "basicTheme": {
5555+ "$type": "site.standard.theme.basic",
5656+ "background": {
5757+ "$type": "site.standard.theme.color#rgb",
5858+ "r": 255,
5959+ "g": 255,
6060+ "b": 255
6161+ },
6262+ "foreground": {
6363+ "$type": "site.standard.theme.color#rgb",
6464+ "r": 31,
6565+ "g": 41,
6666+ "b": 55
6767+ },
6868+ "accent": {
6969+ "$type": "site.standard.theme.color#rgb",
7070+ "r": 59,
7171+ "g": 130,
7272+ "b": 246
7373+ },
7474+ "accentForeground": {
7575+ "$type": "site.standard.theme.color#rgb",
7676+ "r": 255,
7777+ "g": 255,
7878+ "b": 255
7979+ }
8080+ },
8181+ "preferences": {
8282+ "showInDiscover": true
8383+ }
3184}
3285```
33868787+## View the Lexicon
8888+8989+- [View full lexicon schema](https://pdsls.dev/at://did:plc:re3ebnp5v7ffagz6rb6xfei4/com.atproto.lexicon.schema/site.standard.publication)
9090+- [Example record](https://pdsls.dev/at://did:plc:revjuqmkvrw6fnkxppqtszpv/site.standard.publication/3lwafzkjqm25s)
9191+9292+## Extensibility
9393+9494+Lexicons are extendable. Additional properties may be added to better suit the needs of a project.
9595+3496## Related
35973636-- [Document lexicon](/docs/lexicons/document) - Content within publications
9898+- [Document lexicon](/docs/lexicons/document) - Individual documents within publications
9999+- [Theme lexicon](/docs/lexicons/theme) - Publication theming
100100+- [Verification](/docs/verification) - Link publications to a domain
37101- [Quick Start](/docs/quick-start) - Implementation guide
+40
content/docs/lexicons/subscription.mdx
···11+import { Table } from '@/app/components/docs'
22+33+# Subscription Lexicon
44+55+The `site.standard.graph.subscription` lexicon tracks relationships between users and publications.
66+77+## Overview
88+99+Subscriptions enable users to follow publications and receive updates about new content. They represent the social connection between readers and the publications they're interested in.
1010+1111+## Schema
1212+1313+### Required Properties
1414+1515+<Table
1616+ headers={['Property', 'Type', 'Description']}
1717+ rows={[
1818+ ['publication', 'at-uri', 'AT-URI reference to the publication record being subscribed to (ex: at://did:plc:abc123/site.standard.publication/xyz789)'],
1919+ ]}
2020+/>
2121+2222+## Example
2323+2424+```json
2525+{
2626+ "$type": "site.standard.graph.subscription",
2727+ "publication": "at://did:plc:abc123/site.standard.publication/3lwafzkjqm25s"
2828+}
2929+```
3030+3131+## View the Lexicon
3232+3333+- [View full lexicon schema](https://pdsls.dev/at://did:plc:re3ebnp5v7ffagz6rb6xfei4/com.atproto.lexicon.schema/site.standard.graph.subscription)
3434+- [Example record](https://pdsls.dev/at://did:plc:revjuqmkvrw6fnkxppqtszpv/site.standard.graph.subscription/3lz4ynejb4225)
3535+3636+## Related
3737+3838+- [Publication lexicon](/docs/lexicons/publication) - Publications that can be subscribed to
3939+- [Document lexicon](/docs/lexicons/document) - Content from subscribed publications
4040+- [Quick Start](/docs/quick-start) - Implementation guide
+182
content/docs/lexicons/theme.mdx
···11+import { Table } from '@/app/components/docs'
22+33+# Theme Lexicon
44+55+The `site.standard.theme.basic` lexicon provides a simplified theme definition for publications, enabling basic color customization for content display across different platforms and applications.
66+77+## Overview
88+99+This lexicon ensures publications maintain their visual identity across different reading applications and platforms by defining core colors for content display.
1010+1111+## Schema
1212+1313+### Required Properties
1414+1515+<Table
1616+ headers={['Property', 'Type', 'Description']}
1717+ rows={[
1818+ ['background', 'ref', 'Color used for content background (ref → site.standard.theme.color#rgb)'],
1919+ ['foreground', 'ref', 'Color used for content text (ref → site.standard.theme.color#rgb)'],
2020+ ['accent', 'ref', 'Color used for links and button backgrounds (ref → site.standard.theme.color#rgb)'],
2121+ ['accentForeground', 'ref', 'Color used for button text (ref → site.standard.theme.color#rgb)'],
2222+ ]}
2323+/>
2424+2525+## Color Format
2626+2727+Colors are defined using the `site.standard.theme.color#rgb` type from the `site.standard.theme.color` lexicon.
2828+2929+### RGB Color Type
3030+3131+Each color is an object with three required integer properties:
3232+3333+<Table
3434+ headers={['Property', 'Type', 'Range', 'Description']}
3535+ rows={[
3636+ ['r', 'integer', '0-255', 'Red channel value'],
3737+ ['g', 'integer', '0-255', 'Green channel value'],
3838+ ['b', 'integer', '0-255', 'Blue channel value'],
3939+ ]}
4040+/>
4141+4242+### RGBA Color Type
4343+4444+The `site.standard.theme.color` lexicon also defines an `rgba` type for colors with transparency:
4545+4646+<Table
4747+ headers={['Property', 'Type', 'Range', 'Description']}
4848+ rows={[
4949+ ['r', 'integer', '0-255', 'Red channel value'],
5050+ ['g', 'integer', '0-255', 'Green channel value'],
5151+ ['b', 'integer', '0-255', 'Blue channel value'],
5252+ ['a', 'integer', '0-100', 'Alpha (opacity) value, where 0 is transparent and 100 is opaque'],
5353+ ]}
5454+/>
5555+5656+### Color Roles
5757+5858+- **background**: Main surface color for content areas
5959+- **foreground**: Default color for body text and content
6060+- **accent**: Color for interactive elements like links and button backgrounds
6161+- **accentForeground**: Text color used on accent-colored backgrounds (ex: button text)
6262+6363+## Accessibility
6464+6565+When defining theme colors, ensure sufficient contrast ratios:
6666+6767+- **Normal text** (foreground/background): Minimum contrast ratio of 4.5:1
6868+- **Large text** (18pt+): Minimum contrast ratio of 3:1
6969+- **Interactive elements** (accent/accentForeground): Minimum contrast ratio of 4.5:1
7070+7171+Test color combinations to ensure readability across different devices and lighting conditions.
7272+7373+## Usage in Publications
7474+7575+Include the basic theme in your publication record:
7676+7777+```json
7878+{
7979+ "$type": "site.standard.publication",
8080+ "url": "https://myblog.com",
8181+ "name": "My Blog",
8282+ "basicTheme": {
8383+ "$type": "site.standard.theme.basic",
8484+ "background": {
8585+ "$type": "site.standard.theme.color#rgb",
8686+ "r": 255,
8787+ "g": 255,
8888+ "b": 255
8989+ },
9090+ "foreground": {
9191+ "$type": "site.standard.theme.color#rgb",
9292+ "r": 31,
9393+ "g": 41,
9494+ "b": 55
9595+ },
9696+ "accent": {
9797+ "$type": "site.standard.theme.color#rgb",
9898+ "r": 59,
9999+ "g": 130,
100100+ "b": 246
101101+ },
102102+ "accentForeground": {
103103+ "$type": "site.standard.theme.color#rgb",
104104+ "r": 255,
105105+ "g": 255,
106106+ "b": 255
107107+ }
108108+ }
109109+}
110110+```
111111+112112+### Converting from Hex to RGB
113113+114114+Convert hex color codes to RGB objects:
115115+116116+```typescript
117117+function hexToRgb(hex: string): { r: number; g: number; b: number } {
118118+ const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex)
119119+ return result ? {
120120+ r: parseInt(result[1], 16),
121121+ g: parseInt(result[2], 16),
122122+ b: parseInt(result[3], 16)
123123+ } : { r: 0, g: 0, b: 0 }
124124+}
125125+126126+// Example: Convert #3B82F6 to { r: 59, g: 130, b: 246 }
127127+const accentColor = hexToRgb('#3B82F6')
128128+```
129129+130130+## Platform Implementation
131131+132132+### Rendering Content
133133+134134+Platforms should:
135135+1. Read the `basicTheme` from the publication record
136136+2. Convert RGB values to usable color formats (hex, CSS rgb(), etc.)
137137+3. Apply theme colors to their UI components
138138+4. Respect user preferences to override publication themes
139139+140140+### Example Implementation
141141+142142+```typescript
143143+function rgbToHex(color: { r: number; g: number; b: number }): string {
144144+ return `#${color.r.toString(16).padStart(2, '0')}${color.g.toString(16).padStart(2, '0')}${color.b.toString(16).padStart(2, '0')}`
145145+}
146146+147147+function applyPublicationTheme(theme: BasicTheme) {
148148+ document.documentElement.style.setProperty(
149149+ '--publication-bg',
150150+ rgbToHex(theme.background)
151151+ )
152152+153153+ document.documentElement.style.setProperty(
154154+ '--publication-fg',
155155+ rgbToHex(theme.foreground)
156156+ )
157157+158158+ document.documentElement.style.setProperty(
159159+ '--publication-accent',
160160+ rgbToHex(theme.accent)
161161+ )
162162+163163+ document.documentElement.style.setProperty(
164164+ '--publication-accent-fg',
165165+ rgbToHex(theme.accentForeground)
166166+ )
167167+}
168168+```
169169+170170+## Best Practices
171171+172172+1. **Test accessibility**: Always verify color contrast ratios meet WCAG guidelines
173173+2. **Consider readability**: Ensure foreground/background combinations are legible
174174+3. **Test button colors**: Verify accent/accentForeground pairs have sufficient contrast
175175+4. **Respect user preferences**: Allow users to override publication themes if desired
176176+5. **Provide all required properties**: All four color properties are required for a valid theme
177177+178178+## Related
179179+180180+- [Publication lexicon](/docs/lexicons/publication) - Publications can include basicTheme
181181+- [Quick Start](/docs/quick-start) - Implementation guide
182182+- [Implementations](/docs/implementations) - See how platforms use theming
+42
content/docs/permissions.mdx
···11+import { Table } from '@/app/components/docs'
22+import { StandardSite } from '@/app/components/docs'
33+44+# Permissions
55+66+<StandardSite /> provides a permission set for applications to access publications, documents, and subscriptions.
77+88+## Overview
99+1010+Applications that interact with <StandardSite /> records on a user's Personal Data Server (PDS) must request appropriate permissions. Our permission set defines which collections an application can read from and write to.
1111+1212+## Full <StandardSite /> Access
1313+1414+The `site.standard.authFull` permission set provides complete access to all <StandardSite /> features.
1515+1616+### Requesting Permissions
1717+1818+Include `site.standard.authFull` in the OAuth scope when requesting user authorization:
1919+2020+```
2121+include:site.standard.authFull
2222+```
2323+2424+### Granted Permissions
2525+2626+This permission set grants access to the following collections:
2727+2828+<Table
2929+ headers={['Collection', 'Description']}
3030+ rows={[
3131+ ['site.standard.publication', 'Read and write access to publication records'],
3232+ ['site.standard.document', 'Read and write access to document records'],
3333+ ['site.standard.graph.subscription', 'Read and write access to subscription records'],
3434+ ]}
3535+/>
3636+3737+## Related
3838+3939+- [Quick Start](/docs/quick-start) - Get started implementing <StandardSite />
4040+- [Publication lexicon](/docs/lexicons/publication) - Understanding publication records
4141+- [Document lexicon](/docs/lexicons/document) - Understanding document records
4242+- [Subscription lexicon](/docs/lexicons/subscription) - Understanding subscription records
+71-29
content/docs/quick-start.mdx
···11+import { StandardSite } from '@/app/components/docs'
22+13# Quick Start
2433-Get started with Standard.site lexicons in your AT Protocol application.
55+Get started with <StandardSite /> lexicons.
4655-## Prerequisites
77+## What You Need
6877-- An AT Protocol application or PDS
88-- Familiarity with AT Protocol lexicons and records
99+- An AT Protocol [Identity](https://atproto.com/guides/identity)
1010+- A website or blog (any domain works)
9111010-## Basic implementation
1212+## Basic Implementation
11131212-### 1. Reference the lexicons
1414+### 1. Reference the Lexicons
13151414-Standard.site lexicons are published under the `site.standard` namespace. The main lexicons are:
1616+<StandardSite /> lexicons are published under the `site.standard` namespace. The main lexicons are:
15171616-- `site.standard.publication` - Publication metadata
1717-- `site.standard.document` - Document content and metadata
1818-- `site.standard.subscription` - User-publication relationships
1818+- [`site.standard.publication`](/docs/lexicons/publication) - Publication metadata
1919+- [`site.standard.document`](/docs/lexicons/document) - Document content and metadata
2020+- [`site.standard.graph.subscription`](/docs/lexicons/subscription) - User-publication relationships
19212020-### 2. Create a publication
2222+### 2. Create a Publication Record
21232222-```typescript
2323-const publication = {
2424- $type: 'site.standard.publication',
2525- title: 'My Blog',
2626- description: 'A personal blog about technology',
2727- createdAt: new Date().toISOString(),
2424+A publication requires a `url` and `name`:
2525+2626+```json
2727+{
2828+ "$type": "site.standard.publication",
2929+ "url": "https://myblog.com",
3030+ "name": "My Blog",
3131+ "description": "A personal blog about technology",
3232+ "preferences": {
3333+ "showInDiscover": true
3434+ }
2835}
2936```
30373131-### 3. Create a document
3838+### 3. Verify the Publication
32393333-```typescript
3434-const document = {
3535- $type: 'site.standard.document',
3636- publication: 'at://did:plc:.../site.standard.publication/...',
3737- title: 'My First Post',
3838- content: '...', // Your content format
3939- status: 'published',
4040- createdAt: new Date().toISOString(),
4040+Add a `.well-known` endpoint to the domain:
4141+4242+```
4343+https://myblog.com/.well-known/site.standard.publication
4444+```
4545+4646+This should return the publication's AT-URI:
4747+4848+```
4949+at://did:plc:yourDID/site.standard.publication/rkey
5050+```
5151+5252+### 4. Create a Document Record
5353+5454+Documents require `site`, `title`, and `publishedAt`:
5555+5656+```json
5757+{
5858+ "$type": "site.standard.document",
5959+ "site": "at://did:plc:abc123/site.standard.publication/3lwafzkjqm25s",
6060+ "title": "My First Post",
6161+ "path": "/posts/my-first-post",
6262+ "description": "An introduction to my blog",
6363+ "publishedAt": "2024-01-20T14:30:00.000Z",
6464+ "tags": ["introduction", "blog"],
6565+ "textContent": "Full text content here..."
4166}
4267```
43684444-## Next steps
6969+### 5. Verify the Document
7070+7171+Add a `<link>` tag to the document's HTML:
7272+7373+```html
7474+<link
7575+ rel="site.standard.document"
7676+ href="at://did:plc:yourDID/site.standard.document/rkey"
7777+/>
7878+```
7979+8080+## Extensibility
45814646-- Learn about the [Publication](/docs/lexicons/publication) schema in detail
4747-- Explore [Document](/docs/lexicons/document) fields and options
8282+While the minimum required properties are straightforward, additional properties can be added as needed. The lexicons are designed to be starting points, not constraints.
8383+8484+## Next Steps
8585+8686+- Learn about [Verification](/docs/verification) in detail
8787+- Explore the [Publication](/docs/lexicons/publication) schema
8888+- Review [Document](/docs/lexicons/document) properties and options
8989+- Check out [Implementations](/docs/implementations) for tools and examples
+71
content/docs/verification.mdx
···11+import { StandardSite } from '@/app/components/docs'
22+33+# Verification
44+55+Since <StandardSite /> records reference domains and web pages, a verifiable way for these resources to point back to their corresponding records is needed.
66+77+## Overview
88+99+Verification is accomplished using a `.well-known` endpoint for publications, and an HTML `<link>` tag for documents.
1010+1111+When an application needs to verify a record, it fetches the appropriate verification endpoint and checks that the returned value matches the record's AT-URI.
1212+1313+A <StandardSite /> record should only be considered "valid" if the author of the material provides an accurate verification endpoint pointing to the record.
1414+1515+## Publication Verification
1616+1717+To verify a publication, add a `.well-known` endpoint to the domain:
1818+1919+```
2020+/.well-known/site.standard.publication
2121+```
2222+2323+The endpoint should return the AT-URI of the publication record:
2424+2525+```
2626+at://did:plc:abc123/site.standard.publication/rkey
2727+```
2828+2929+### Non-root Publications
3030+3131+If the publication does not live at the domain root, append the publication path to the endpoint:
3232+3333+```
3434+/.well-known/site.standard.publication/path/to/publication
3535+```
3636+3737+## Document Verification
3838+3939+To verify an individual document, include a `<link>` tag in the document's `<head>` that references its AT-URI.
4040+4141+### HTML Example
4242+4343+```html
4444+<link
4545+ rel="site.standard.document"
4646+ href="at://did:plc:xyz789/site.standard.document/rkey"
4747+/>
4848+```
4949+5050+This confirms the association between the rendered document and its `site.standard.document` record.
5151+5252+## Verification Flow
5353+5454+1. An application discovers a <StandardSite /> record
5555+2. The record contains a `url` (for publications) or `site` + `path` (for documents)
5656+3. The application fetches the verification endpoint from that URL
5757+4. The application checks if the returned AT-URI matches the record
5858+5. If they match, the record is verified
5959+6060+## Best Practices
6161+6262+- Always implement verification for production records
6363+- Use HTTPS for all publication and document URLs
6464+- Keep AT-URIs consistent across records and verification endpoints
6565+- Update verification endpoints when migrating records to a new DID
6666+6767+## Related
6868+6969+- [Publication lexicon](/docs/lexicons/publication) - Understanding publication records
7070+- [Document lexicon](/docs/lexicons/document) - Understanding document records
7171+- [Quick Start](/docs/quick-start) - Implementation guide
···11+# Standard.site Documentation
22+33+## Overview
44+Standard.site provides AT Protocol lexicons for long-form publishing on the open social web.
55+66+## Navigation
77+88+### Getting Started
99+- Introduction: https://standard.site/docs/introduction
1010+ Overview of Standard.site lexicons and core concepts
1111+1212+- Quick Start: https://standard.site/docs/quick-start
1313+ Step-by-step guide to implementing Standard.site lexicons
1414+1515+- Permissions: https://standard.site/docs/permissions
1616+ Understanding record permissions and access control
1717+1818+- Verification: https://standard.site/docs/verification
1919+ Linking records to domains for authenticity
2020+2121+### Core Lexicons
2222+- Publication: https://standard.site/docs/lexicons/publication
2323+ `site.standard.publication` - Collection metadata and theming
2424+2525+- Document: https://standard.site/docs/lexicons/document
2626+ `site.standard.document` - Individual document records
2727+2828+- Subscription: https://standard.site/docs/lexicons/subscription
2929+ `site.standard.graph.subscription` - Follow relationships
3030+3131+- Theme: https://standard.site/docs/lexicons/theme
3232+ `site.standard.theme` - Theming configuration
3333+3434+### Resources
3535+- Implementations: https://standard.site/docs/implementations
3636+ Tools and platforms using Standard.site lexicons
3737+3838+- FAQ: https://standard.site/docs/faq
3939+ Common questions and answers
4040+4141+## Features
4242+- All documentation pages support anchor links (click any heading to copy its link)
4343+- Each page provides a "Markdown" link in the footer for direct AI agent consumption
4444+- Full markdown source available via API: /api/docs/markdown/{slug}
4545+4646+## API Access
4747+GET /api/docs/markdown/{slug} - Returns the raw markdown content of any documentation page
4848+Example: /api/docs/markdown/introduction
4949+5050+## Key Concepts
5151+- AT Protocol: Authenticated Transfer Protocol - decentralized social networking
5252+- PDS: Personal Data Server - stores user data and records
5353+- Lexicons: Schemas that define record types in AT Protocol
5454+- NSID: Namespaced Identifier - unique identifier format for lexicons
5555+5656+## Implementation Quick Reference
5757+1. Create publication record with site.standard.publication lexicon
5858+2. Create document records with site.standard.document lexicon
5959+3. Link documents to publication via publication reference
6060+4. Implement verification to link records to your domain
6161+5. Support subscription records for follow functionality