A CLI for publishing standard.site documents to ATProto sequoia.pub
standard site lexicon cli publishing

Add subscribe section to documentation and update navigation links

authored by

Heath Stewart and committed by tangled.org 43be9f09 eb6c76c2

+192
+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
··· 34 34 { text: "Setup", link: "/setup" }, 35 35 { text: "Publishing", link: "/publishing" }, 36 36 { text: "Comments", link: "/comments" }, 37 + { text: "Subscribe", link: "/subscribe" }, 37 38 { text: "Verifying", link: "/verifying" }, 38 39 { text: "Workflows", link: "/workflows" }, 39 40 ],