phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
78165ad3be9a4b4faad2011fc2fbf3200a3fb826
StarPunk/docs/examples/identity-page-customization-guide.md
Phil Skentelbery 68669b9a6a 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>
2025-11-19 13:03:49 -07:00

7.3 KiB
Raw Blame History

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

<!-- 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

<!-- 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

<!-- 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

<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:

<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):

<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

    color: #333;        /* Text color */
background: #fff;   /* Background color */
color: #0066cc;     /* Link color */

  2. Fonts: Modify the font-family stack

    font-family: Georgia, serif;  /* For a more classic look */

  3. Layout: Adjust spacing and widths

    max-width: 800px;   /* Wider content */
padding: 4rem;      /* More padding */

Multiple Profiles

For multiple online identities, add more h-cards:

<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 lang="es">  <!-- Spanish -->
<meta charset="utf-8">  <!-- Supports all Unicode characters -->

Accessibility Improvements

<!-- 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:

<!-- Hosted at https://example.com but u-url says: -->
<a class="u-url" href="https://different.com">

✅ Correct:

<!-- URLs must match exactly -->
<a class="u-url" href="https://example.com">

2. Missing HTTPS

❌ Wrong:

<a class="u-url" href="http://example.com">

✅ Correct:

<a class="u-url" href="https://example.com">

3. Broken Social Links

❌ Wrong:

<!-- Empty href -->
<a href="" rel="me">GitHub</a>

<!-- Placeholder text -->
<a href="https://github.com/yourusername" rel="me">

✅ Correct:

<!-- Real, working link -->
<a href="https://github.com/actualusername" rel="me">GitHub</a>

4. Multiple u-url Values

❌ Wrong:

<a class="u-url" href="https://example.com">Example</a>
<a class="u-url" href="https://other.com">Other</a>

✅ Correct:

<!-- 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

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):

    <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

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

Reference in New Issue View Git Blame Copy Permalink