heaths.dev
forked from
stevedylan.dev/sequoia
A CLI for publishing standard.site documents to ATProto
Add subscribe section to documentation and update navigation links
+192
+191
docs/docs/pages/subscribe.mdx
+191
docs/docs/pages/subscribe.mdx
···
1
+
# Subscribe
2
+
3
+
Sequoia provides a subscribe button web component that lets your readers subscribe to your publication directly from your site using their Bluesky account.
4
+
5
+
## Setup
6
+
7
+
Run the following command in your project to install the subscribe web component. It will ask you where you would like to store the component file.
8
+
9
+
```bash [Terminal]
10
+
sequoia add sequoia-subscribe
11
+
```
12
+
13
+
The component will look for your publication AT URI from your site's `/.well-known/site.standard.publication` endpoint automatically, so no additional configuration is required for most setups.
14
+
15
+
## Usage
16
+
17
+
Since `sequoia-subscribe` is a standard Web Component, it works with any framework. Choose your setup below:
18
+
19
+
:::code-group
20
+
21
+
```html [HTML]
22
+
<body>
23
+
<h1>My Publication</h1>
24
+
<!--Content-->
25
+
26
+
<sequoia-subscribe></sequoia-subscribe>
27
+
<script type="module" src="./src/components/sequoia-subscribe.js"></script>
28
+
</body>
29
+
```
30
+
31
+
```tsx [React]
32
+
// Import the component (registers the custom element)
33
+
import './components/sequoia-subscribe.js';
34
+
35
+
function HomePage() {
36
+
return (
37
+
<main>
38
+
<h1>My Publication</h1>
39
+
{/* Content */}
40
+
<sequoia-subscribe />
41
+
</main>
42
+
);
43
+
}
44
+
```
45
+
46
+
```vue [Vue]
47
+
<script setup>
48
+
import './components/sequoia-subscribe.js';
49
+
</script>
50
+
51
+
<template>
52
+
<main>
53
+
<h1>My Publication</h1>
54
+
<!-- Content -->
55
+
<sequoia-subscribe />
56
+
</main>
57
+
</template>
58
+
```
59
+
60
+
```svelte [Svelte]
61
+
<script>
62
+
import './components/sequoia-subscribe.js';
63
+
</script>
64
+
65
+
<main>
66
+
<h1>My Publication</h1>
67
+
<!-- Content -->
68
+
<sequoia-subscribe />
69
+
</main>
70
+
```
71
+
72
+
```astro [Astro]
73
+
<main>
74
+
<h1>My Publication</h1>
75
+
<!-- Content -->
76
+
<sequoia-subscribe />
77
+
<script>
78
+
import './components/sequoia-subscribe.js';
79
+
</script>
80
+
</main>
81
+
```
82
+
83
+
:::
84
+
85
+
### TypeScript Support
86
+
87
+
If you're using TypeScript with React, add this type declaration to avoid JSX errors:
88
+
89
+
```ts [custom-elements.d.ts]
90
+
declare namespace JSX {
91
+
interface IntrinsicElements {
92
+
'sequoia-subscribe': React.DetailedHTMLProps<
93
+
React.HTMLAttributes<HTMLElement> & {
94
+
'publication-uri'?: string;
95
+
'callback-uri'?: string;
96
+
label?: string;
97
+
hide?: string;
98
+
},
99
+
HTMLElement
100
+
>;
101
+
}
102
+
}
103
+
```
104
+
105
+
### Vue Configuration
106
+
107
+
For Vue, you may need to configure the compiler to recognize custom elements:
108
+
109
+
```ts [vite.config.ts]
110
+
export default defineConfig({
111
+
plugins: [
112
+
vue({
113
+
template: {
114
+
compilerOptions: {
115
+
isCustomElement: (tag) => tag === 'sequoia-subscribe'
116
+
}
117
+
}
118
+
})
119
+
]
120
+
});
121
+
```
122
+
123
+
## Configuration
124
+
125
+
The subscribe web component has several configuration options available.
126
+
127
+
### Attributes
128
+
129
+
The `<sequoia-subscribe>` component accepts the following attributes:
130
+
131
+
| Attribute | Type | Default | Description |
132
+
|-----------|------|---------|-------------|
133
+
| `publication-uri` | `string` | - | AT Protocol URI for the publication. Optional if a `/.well-known/site.standard.publication` endpoint exists on the host site. |
134
+
| `callback-uri` | `string` | `https://sequoia.pub/subscribe` | Redirect URI used for the OAuth authentication flow. |
135
+
| `label` | `string` | `Subscribe on Bluesky` | Button label text. |
136
+
| `hide` | `string` | - | Set to `"auto"` to hide the component if no publication URI is detected. |
137
+
138
+
```html
139
+
<!-- Use attributes for explicit control -->
140
+
<sequoia-subscribe
141
+
publication-uri="at://did:plc:example/site.standard.publication/abc123"
142
+
label="Follow on Bluesky">
143
+
</sequoia-subscribe>
144
+
```
145
+
146
+
### Events
147
+
148
+
The component dispatches custom events you can listen to:
149
+
150
+
| Event | Description | `detail` |
151
+
|-------|-------------|----------|
152
+
| `sequoia-subscribed` | Fired when the subscription is created successfully. | `{ publicationUri: string, recordUri: string }` |
153
+
| `sequoia-subscribe-error` | Fired when the subscription fails. | `{ message: string }` |
154
+
155
+
```js
156
+
const btn = document.querySelector('sequoia-subscribe');
157
+
158
+
btn.addEventListener('sequoia-subscribed', (e) => {
159
+
console.log('Subscribed!', e.detail.recordUri);
160
+
});
161
+
162
+
btn.addEventListener('sequoia-subscribe-error', (e) => {
163
+
console.error('Subscription failed:', e.detail.message);
164
+
});
165
+
```
166
+
167
+
### Styling
168
+
169
+
The component uses CSS custom properties for theming. Set these in your `:root` or parent element to customize the appearance:
170
+
171
+
| CSS Property | Default | Description |
172
+
|--------------|---------|-------------|
173
+
| `--sequoia-fg-color` | `#1f2937` | Text color |
174
+
| `--sequoia-bg-color` | `#ffffff` | Background color |
175
+
| `--sequoia-border-color` | `#e5e7eb` | Border color |
176
+
| `--sequoia-accent-color` | `#2563eb` | Button background color |
177
+
| `--sequoia-secondary-color` | `#6b7280` | Secondary text color |
178
+
| `--sequoia-border-radius` | `8px` | Border radius for the button |
179
+
180
+
### Example: Match Site Theme
181
+
182
+
```css
183
+
:root {
184
+
--sequoia-accent-color: #3A5A40;
185
+
--sequoia-border-radius: 6px;
186
+
--sequoia-bg-color: #F5F3EF;
187
+
--sequoia-fg-color: #2C2C2C;
188
+
--sequoia-border-color: #D5D1C8;
189
+
--sequoia-secondary-color: #8B7355;
190
+
}
191
+
```
+1
docs/vocs.config.ts
+1
docs/vocs.config.ts