docs: add reference IndieAuth identity page implementation
Add minimal, production-ready static HTML identity page as reference implementation for IndieAuth authentication. Includes: - Complete identity-page.html with h-card and IndieAuth endpoints - Architectural documentation and rationale - ADR-010: Static Identity Page decision record - Customization guide for users The example is zero-dependency, copy-paste ready, and guaranteed to work with IndieLogin.com and StarPunk. Pre-configured for thesatelliteoflove.com as working example. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
334
docs/examples/identity-page-customization-guide.md
Normal file
334
docs/examples/identity-page-customization-guide.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# IndieAuth Identity Page Customization Guide
|
||||
|
||||
## Quick Start
|
||||
|
||||
The identity page template (`identity-page.html`) is a complete, working IndieAuth identity page. To use it:
|
||||
|
||||
1. Download `identity-page.html`
|
||||
2. Edit the marked sections with your information
|
||||
3. Upload to your domain root as `index.html`
|
||||
4. Test at https://indielogin.com/
|
||||
|
||||
## What to Customize
|
||||
|
||||
### Required Changes
|
||||
|
||||
These MUST be changed for the page to work correctly:
|
||||
|
||||
#### 1. Your Name
|
||||
```html
|
||||
<!-- Change this -->
|
||||
<title>Phil Skents</title>
|
||||
<h1 class="p-name">Phil Skents</h1>
|
||||
|
||||
<!-- To this -->
|
||||
<title>Your Name</title>
|
||||
<h1 class="p-name">Your Name</h1>
|
||||
```
|
||||
|
||||
#### 2. Your Domain
|
||||
```html
|
||||
<!-- Change this -->
|
||||
<a class="u-url" href="https://thesatelliteoflove.com" rel="me">
|
||||
https://thesatelliteoflove.com
|
||||
</a>
|
||||
|
||||
<!-- To this (must match where you host this file) -->
|
||||
<a class="u-url" href="https://yourdomain.com" rel="me">
|
||||
https://yourdomain.com
|
||||
</a>
|
||||
```
|
||||
|
||||
### Optional Customizations
|
||||
|
||||
#### Add Your Photo
|
||||
```html
|
||||
<!-- Uncomment and modify this line -->
|
||||
<img class="u-photo" src="/avatar.jpg" alt="Your Name">
|
||||
```
|
||||
|
||||
Photo tips:
|
||||
- Use a square image (1:1 ratio)
|
||||
- 240x240 pixels minimum recommended
|
||||
- JPEG or PNG format
|
||||
- Under 100KB for fast loading
|
||||
|
||||
#### Add Your Bio
|
||||
```html
|
||||
<p class="p-note">
|
||||
Your bio here. Keep it brief - 1-2 sentences.
|
||||
</p>
|
||||
```
|
||||
|
||||
#### Add Social Media Links
|
||||
|
||||
Uncomment and modify the social links section:
|
||||
|
||||
```html
|
||||
<li>
|
||||
<a href="https://github.com/yourusername" rel="me">
|
||||
GitHub: @yourusername
|
||||
</a>
|
||||
</li>
|
||||
```
|
||||
|
||||
**Important**: Only add profiles you control. Some services that support rel="me":
|
||||
- GitHub (automatic)
|
||||
- Mastodon (automatic)
|
||||
- Personal websites
|
||||
- Some IndieWeb services
|
||||
|
||||
#### Add Micropub Endpoint
|
||||
|
||||
If you have a Micropub server (like StarPunk):
|
||||
|
||||
```html
|
||||
<link rel="micropub" href="https://yourmicropub.example.com/micropub">
|
||||
```
|
||||
|
||||
## Advanced Customizations
|
||||
|
||||
### Custom Styling
|
||||
|
||||
The template includes minimal inline CSS. To customize:
|
||||
|
||||
1. **Colors**: Change the color values in the `<style>` section
|
||||
```css
|
||||
color: #333; /* Text color */
|
||||
background: #fff; /* Background color */
|
||||
color: #0066cc; /* Link color */
|
||||
```
|
||||
|
||||
2. **Fonts**: Modify the font-family stack
|
||||
```css
|
||||
font-family: Georgia, serif; /* For a more classic look */
|
||||
```
|
||||
|
||||
3. **Layout**: Adjust spacing and widths
|
||||
```css
|
||||
max-width: 800px; /* Wider content */
|
||||
padding: 4rem; /* More padding */
|
||||
```
|
||||
|
||||
### Multiple Profiles
|
||||
|
||||
For multiple online identities, add more h-cards:
|
||||
|
||||
```html
|
||||
<div class="h-card">
|
||||
<h2 class="p-name">Professional Name</h2>
|
||||
<a class="u-url" href="https://professional.com" rel="me">
|
||||
https://professional.com
|
||||
</a>
|
||||
</div>
|
||||
|
||||
<div class="h-card">
|
||||
<h2 class="p-name">Personal Name</h2>
|
||||
<a class="u-url" href="https://personal.com" rel="me">
|
||||
https://personal.com
|
||||
</a>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Language Support
|
||||
|
||||
For non-English pages:
|
||||
|
||||
```html
|
||||
<html lang="es"> <!-- Spanish -->
|
||||
<meta charset="utf-8"> <!-- Supports all Unicode characters -->
|
||||
```
|
||||
|
||||
### Accessibility Improvements
|
||||
|
||||
```html
|
||||
<!-- Add language attributes -->
|
||||
<html lang="en">
|
||||
|
||||
<!-- Add descriptive alt text -->
|
||||
<img class="u-photo" src="/avatar.jpg" alt="Headshot of Your Name">
|
||||
|
||||
<!-- Add skip navigation -->
|
||||
<a href="#main" class="skip-link">Skip to content</a>
|
||||
```
|
||||
|
||||
## Testing Your Customizations
|
||||
|
||||
### 1. Local Testing
|
||||
|
||||
Open the file in your browser:
|
||||
```
|
||||
file:///path/to/identity-page.html
|
||||
```
|
||||
|
||||
Check:
|
||||
- [ ] Your name appears correctly
|
||||
- [ ] Links work (won't authenticate locally)
|
||||
- [ ] Page looks good on mobile (resize browser)
|
||||
|
||||
### 2. HTML Validation
|
||||
|
||||
Visit https://validator.w3.org/:
|
||||
1. Choose "Validate by File Upload"
|
||||
2. Upload your modified file
|
||||
3. Fix any errors shown
|
||||
|
||||
### 3. Microformats Testing
|
||||
|
||||
Visit https://indiewebify.me/:
|
||||
1. After uploading to your domain
|
||||
2. Use "Validate h-card"
|
||||
3. Enter your domain
|
||||
4. Verify your information is detected
|
||||
|
||||
### 4. IndieAuth Testing
|
||||
|
||||
Visit https://indielogin.com/:
|
||||
1. Enter your domain
|
||||
2. Should see "IndieAuth.com" as option
|
||||
3. Click to authenticate
|
||||
4. Should complete successfully
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### 1. URL Mismatches
|
||||
|
||||
❌ **Wrong**:
|
||||
```html
|
||||
<!-- Hosted at https://example.com but u-url says: -->
|
||||
<a class="u-url" href="https://different.com">
|
||||
```
|
||||
|
||||
✅ **Correct**:
|
||||
```html
|
||||
<!-- URLs must match exactly -->
|
||||
<a class="u-url" href="https://example.com">
|
||||
```
|
||||
|
||||
### 2. Missing HTTPS
|
||||
|
||||
❌ **Wrong**:
|
||||
```html
|
||||
<a class="u-url" href="http://example.com">
|
||||
```
|
||||
|
||||
✅ **Correct**:
|
||||
```html
|
||||
<a class="u-url" href="https://example.com">
|
||||
```
|
||||
|
||||
### 3. Broken Social Links
|
||||
|
||||
❌ **Wrong**:
|
||||
```html
|
||||
<!-- Empty href -->
|
||||
<a href="" rel="me">GitHub</a>
|
||||
|
||||
<!-- Placeholder text -->
|
||||
<a href="https://github.com/yourusername" rel="me">
|
||||
```
|
||||
|
||||
✅ **Correct**:
|
||||
```html
|
||||
<!-- Real, working link -->
|
||||
<a href="https://github.com/actualusername" rel="me">GitHub</a>
|
||||
```
|
||||
|
||||
### 4. Multiple u-url Values
|
||||
|
||||
❌ **Wrong**:
|
||||
```html
|
||||
<a class="u-url" href="https://example.com">Example</a>
|
||||
<a class="u-url" href="https://other.com">Other</a>
|
||||
```
|
||||
|
||||
✅ **Correct**:
|
||||
```html
|
||||
<!-- Only one u-url that matches your domain -->
|
||||
<a class="u-url" href="https://example.com">Example</a>
|
||||
<a href="https://other.com">Other</a> <!-- No u-url class -->
|
||||
```
|
||||
|
||||
## Deployment Options
|
||||
|
||||
### Static Hosting Services
|
||||
|
||||
The identity page works on any static host:
|
||||
|
||||
1. **GitHub Pages**
|
||||
- Free with GitHub account
|
||||
- Upload as `index.html` in repository
|
||||
- Enable Pages in repository settings
|
||||
|
||||
2. **Netlify**
|
||||
- Drag and drop deployment
|
||||
- Free tier available
|
||||
- Automatic HTTPS
|
||||
|
||||
3. **Vercel**
|
||||
- Simple deployment
|
||||
- Free tier available
|
||||
- Good performance
|
||||
|
||||
4. **Traditional Web Hosting**
|
||||
- Upload via FTP/SFTP
|
||||
- Place in document root
|
||||
- Ensure HTTPS is enabled
|
||||
|
||||
### File Naming
|
||||
|
||||
- `index.html` - For domain root (https://example.com/)
|
||||
- `identity.html` - For subfolder (https://example.com/identity.html)
|
||||
- Any name works, but update your StarPunk configuration accordingly
|
||||
|
||||
## Integration with StarPunk
|
||||
|
||||
Once your identity page is working:
|
||||
|
||||
1. **Configure StarPunk** to use your identity URL:
|
||||
```
|
||||
IDENTITY_URL=https://yourdomain.com
|
||||
```
|
||||
|
||||
2. **Test Authentication**:
|
||||
- Visit your StarPunk instance
|
||||
- Click "Sign In"
|
||||
- Enter your identity URL
|
||||
- Should authenticate successfully
|
||||
|
||||
3. **Add Micropub Endpoint** (after StarPunk is running):
|
||||
```html
|
||||
<link rel="micropub" href="https://starpunk.yourdomain.com/micropub">
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Page Not Found
|
||||
- Ensure file is named correctly (usually `index.html`)
|
||||
- Check file is in correct directory (document root)
|
||||
- Verify domain is configured correctly
|
||||
|
||||
### Authentication Fails
|
||||
- Verify HTTPS is working
|
||||
- Check u-url matches actual URL exactly
|
||||
- Ensure no typos in endpoint URLs
|
||||
- Test with browser developer tools for errors
|
||||
|
||||
### h-card Not Detected
|
||||
- Check class names are exact (`h-card`, `p-name`, `u-url`)
|
||||
- Ensure HTML structure is valid
|
||||
- Verify no typos in microformat classes
|
||||
|
||||
### Social Links Not Working
|
||||
- Only include rel="me" on profiles you control
|
||||
- Check URLs are correct and working
|
||||
- Some services don't support rel="me" back-linking
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **IndieWeb Chat**: https://indieweb.org/discuss
|
||||
- **StarPunk Issues**: [GitHub repository]
|
||||
- **IndieAuth Spec**: https://indieauth.spec.indieweb.org/
|
||||
- **Microformats Wiki**: http://microformats.org/
|
||||
|
||||
Remember: The simplest solution is often the best. Don't add complexity unless you need it.
|
||||
Reference in New Issue
Block a user