# 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://www.w3.org/TR/indieauth/
- **Microformats Wiki**: http://microformats.org/

Remember: The simplest solution is often the best. Don't add complexity unless you need it.