Phil Skentelbery
68669b9a6a
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>
334 lines
7.3 KiB
Markdown
334 lines
7.3 KiB
Markdown
# 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. |