ewancroft.uk / whtwnd-to-leaflet
A WhiteWind blog to Leaflet publication conversion tool
fork atom
whtwnd-to-leaflet / CONTRIBUTING.md
at main 7.3 kB view raw view code

Contributing to WhiteWind to Leaflet Converter#

Thank you for your interest in contributing to the WhiteWind to Leaflet converter! This guide will help you get started with contributing to this project.

🚀 Getting Started#

Prerequisites#

  • Node.js (version 18 or higher recommended)
  • npm (comes with Node.js)
  • Basic knowledge of TypeScript, Svelte, and web development

Setting Up the Development Environment#

  1. Fork the repository on GitHub

  2. Clone your fork locally:

    git clone https://github.com/YOUR_USERNAME/whtwnd-to-leaflet.git
cd whtwnd-to-leaflet

  3. Install dependencies:

    npm install

  4. Start the development server:

    npm run dev

  5. Open your browser and navigate to http://localhost:5173

📁 Project Structure#

Understanding the project structure will help you navigate and contribute effectively:

src/
├── routes/
│   ├── +layout.svelte         # Global layout
│   └── +page.svelte           # Main application page
├── lib/
│   ├── convert.ts             # Core conversion logic
│   ├── styles.css             # Custom styles
│   └── variables.css          # CSS custom properties
├── types/
│   └── file-saver.d.ts        # Type declarations
└── app.css                    # Global styles entry point

Key Files to Understand#

  • src/lib/convert.ts - Contains all conversion logic including:
    • TID generation
    • Markdown to Leaflet blocks parsing
    • Rich text processing with facets
    • URL conversion utilities
  • src/routes/+page.svelte - The main UI component with:
    • Form handling
    • State management
    • User interaction logic
  • src/lib/styles.css - Custom styling that works with CSS custom properties

🛠️ Development Workflow#

Code Style#

This project uses Prettier for code formatting. The configuration is in .prettierrc:

  • Tabs for indentation
  • Single quotes for strings
  • No trailing commas
  • 100 character print width

Before submitting, ensure your code is formatted:

npm run format

Type Checking#

The project uses TypeScript with strict settings. Run type checking with:

npm run check

For continuous type checking during development:

npm run check:watch

Building and Testing#

Build the project to ensure everything works:

npm run build

Preview the built version:

npm run preview

🎯 Areas for Contribution#

High Priority Areas#

  1. Conversion Logic Improvements
  • Better markdown parsing edge cases
  • Enhanced rich text facet extraction
  • More robust error handling
  1. User Experience
  • Better error messages and validation
  • Progress indicators for long operations
  • Improved responsive design
  1. Testing
  • Unit tests for conversion functions
  • Integration tests for UI components
  • End-to-end testing

Medium Priority Areas#

  1. Additional Features
  • Batch processing improvements
  • Export format options
  • Configuration presets
  1. Documentation
  • Code comments and documentation
  • User guide improvements
  • API documentation
  1. Performance
  • Large file handling optimization
  • Memory usage improvements
  • Bundle size optimization

📝 Contribution Guidelines#

Before You Start#

  1. Check existing issues to see if someone is already working on what you want to do
  2. Open an issue to discuss major changes before implementing them
  3. Search existing pull requests to avoid duplicate work

Making Changes#

  1. Create a new branch for your feature or bugfix:

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

  2. Make your changes following the project’s coding standards

  3. Test your changes thoroughly:

  • Test the conversion with various WhiteWind export formats
  • Verify the output works with Leaflet
  • Check responsive design on different screen sizes

  1. Commit your changes with clear, descriptive messages:

    git commit -m "feat: add support for nested blockquotes"
# or
git commit -m "fix: handle empty content fields gracefully"

Pull Request Process#

  1. Update documentation if your changes affect user-facing functionality

  2. Ensure all checks pass:

    npm run format
npm run check
npm run build

  3. Create a pull request with:

  • Clear title describing the change
  • Detailed description of what was changed and why
  • Screenshots if UI changes are involved
  • Reference to related issues
  1. Respond to feedback promptly and make requested changes

🐛 Bug Reports#

When reporting bugs, please include:

  • Browser and version
  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Sample WhiteWind JSON that causes the issue (if applicable)
  • Console errors (if any)

Use this template:

**Bug Description:**
A clear description of the bug.

**Steps to Reproduce:**
1. Go to...
2. Click on...
3. Enter...

**Expected Behavior:**
What should have happened.

**Actual Behavior:**
What actually happened.

**Environment:**
- Browser: [e.g., Chrome 120]
- OS: [e.g., Windows 11]
- Version: [e.g., latest main branch]

**Additional Context:**
Any other relevant information.

💡 Feature Requests#

For feature requests, please:

  1. Check existing issues first
  2. Describe the use case clearly
  3. Explain why the feature would be valuable
  4. Provide examples if possible

🔧 Technical Details#

Key Technologies#

  • SvelteKit - Full-stack framework
  • TypeScript - Type safety
  • Tailwind CSS v4 - Utility-first styling
  • JSZip - ZIP file generation
  • File-saver - File download functionality

Conversion Process#

The conversion happens in these main steps:

  1. Parse WhiteWind JSON - Handle different export formats
  2. Generate Publication Record - Create the main publication schema
  3. Convert Entries - Transform each entry into Leaflet documents
  4. Process Markdown - Parse markdown into Leaflet blocks
  5. Handle Rich Text - Extract and convert text formatting
  6. Convert URLs - Transform blob URLs to AT-URIs

AT Protocol Integration#

This tool works with the AT Protocol ecosystem:

  • WhiteWind - Source blog platform
  • Leaflet - Target publication platform
  • AT-URIs - Proper URI format conversion
  • DIDs - Decentralized identity handling

📜 Code of Conduct#

  • Be respectful and inclusive
  • Provide constructive feedback
  • Focus on the issue, not the person
  • Help create a welcoming environment for all contributors

📞 Getting Help#

If you need help:

  1. Check the README for basic usage information
  2. Look through existing issues for similar questions
  3. Open a new issue with the “question” label
  4. Be specific about what you’re trying to do

🎉 Recognition#

Contributors will be recognized in:

  • GitHub contributors list
  • Release notes for significant contributions
  • Project documentation

Thank you for contributing to making WhiteWind to Leaflet conversion better for everyone! 🍃