diff --git a/docs/docs/pages/cli-reference.mdx b/docs/docs/pages/cli-reference.mdx index d76b3ea..3d2a9ba 100644 --- a/docs/docs/pages/cli-reference.mdx +++ b/docs/docs/pages/cli-reference.mdx @@ -32,6 +32,24 @@ FLAGS: Use this as an alternative to `login` when OAuth isn't available or for CI environments. +## `add` + +```bash [Terminal] +sequoia add +> Add a UI component to your project + +ARGUMENTS: + component - The name of the component to add + +FLAGS: + --help, -h - show help [optional] +``` + +Available components: +- `sequoia-comments` - Display Bluesky replies as comments on your blog posts + +The component will be installed to the directory specified in `ui.components` (default: `src/components`). See the [Comments guide](/comments) for usage details. + ## `init` ```bash [Terminal] diff --git a/docs/docs/pages/comments.mdx b/docs/docs/pages/comments.mdx new file mode 100644 index 0000000..f916663 --- /dev/null +++ b/docs/docs/pages/comments.mdx @@ -0,0 +1,83 @@ +# Comments + +Sequoia has a small UI trick up its sleve that lets you easily display comments on your blog posts through Bluesky posts. This is the general flow: + +1. Setup your blog with `sequoia init`, and when prompted at the end to enable BlueSky posts, select `yes`. +2. When you run `sequoia pubish` the CLI will publish a BlueSky post and link it to your `site.standard.document` record for your post. +3. As people reply to the BlueSky post, the replies can be rendered as comments below your post using the Sequoia UI web component. + +## Setup + +Run the following command in your project to install the comments web component. It will ask you where you would like to store the component file. + +```bash [Terminal] +sequoia add sequoia-comments +``` + +Then in your HTML or blog post template, import the component with a script tag or module import. + +```html + +

Blog Post Title

+ +

Comments

+ + // [!code focus] + // [!code focus] + + + +``` + +The web components will look for the `` in your HTML head, then using the `atUri` fetch the post and the replies. + +::::tip +For more information on the `` tags, check out the [verification guide](/verifying) +:::: + +## Configuration + +The comments web component has several configuration options available. + +### Attributes + +The `` component accepts the following attributes: + +| Attribute | Type | Default | Description | +|-----------|------|---------|-------------| +| `document-uri` | `string` | - | AT Protocol URI for the document. Optional if a `` tag exists in the page head. | +| `depth` | `number` | `6` | Maximum depth of nested replies to fetch. | + +```html + + + +``` + +### Styling + +The component uses CSS custom properties for theming. Set these in your `:root` or parent element to customize the appearance: + +| CSS Property | Default | Description | +|--------------|---------|-------------| +| `--sequoia-fg-color` | `#1f2937` | Text color | +| `--sequoia-bg-color` | `#ffffff` | Background color | +| `--sequoia-border-color` | `#e5e7eb` | Border color | +| `--sequoia-accent-color` | `#2563eb` | Accent/link color | +| `--sequoia-secondary-color` | `#6b7280` | Secondary text color (handles, timestamps) | +| `--sequoia-border-radius` | `8px` | Border radius for cards and buttons | + +### Example: Dark Theme + +```css +:root { + --sequoia-accent-color: #3A5A40; + --sequoia-border-radius: 12px; + --sequoia-bg-color: #1a1a1a; + --sequoia-fg-color: #F5F3EF; + --sequoia-border-color: #333; + --sequoia-secondary-color: #8B7355; +} +``` diff --git a/docs/docs/pages/config.mdx b/docs/docs/pages/config.mdx index cf79b46..0d1a47c 100644 --- a/docs/docs/pages/config.mdx +++ b/docs/docs/pages/config.mdx @@ -19,8 +19,10 @@ | `removeIndexFromSlug` | `boolean` | No | `false` | Remove `/index` or `/_index` suffix from slugs | | `stripDatePrefix` | `boolean` | No | `false` | Remove `YYYY-MM-DD-` date prefixes from slugs (Jekyll-style) | | `bluesky` | `object` | No | - | Bluesky posting configuration | -| `bluesky.enabled` | `boolean` | No | `false` | Post to Bluesky when publishing documents | +| `bluesky.enabled` | `boolean` | No | `false` | Post to Bluesky when publishing documents (also enables [comments](/comments)) | | `bluesky.maxAgeDays` | `number` | No | `30` | Only post documents published within this many days | +| `ui` | `object` | No | - | UI components configuration | +| `ui.components` | `string` | No | `"src/components"` | Directory where UI components are installed | ### Example @@ -41,6 +43,9 @@ "bluesky": { "enabled": true, "maxAgeDays": 30 + }, + "ui": { + "components": "src/components" } } ``` diff --git a/docs/docs/pages/publishing.mdx b/docs/docs/pages/publishing.mdx index c4d88b0..0ef6c07 100644 --- a/docs/docs/pages/publishing.mdx +++ b/docs/docs/pages/publishing.mdx @@ -66,6 +66,12 @@ If your framework uses a different field name (like `private` or `hidden`), conf } ``` +## Comments + +When Bluesky posting is enabled, Sequoia links each published document to its corresponding Bluesky post. This enables comments on your blog posts through Bluesky replies. + +To display comments on your site, use the `sequoia-comments` web component. See the [Comments guide](/comments) for setup instructions. + ## Troubleshooting - If you have files in your markdown directory that should be ignored, use the [`ignore` array in the config](/config#ignoring-files).