Skip to main content

Contributing to Pixlr Documentation

Thank you for your interest in contributing to the Pixlr Group Documentation! This guide will help you get the development environment set up and running.

Prerequisites​

Before you begin, make sure you have the following installed:

  • Node.js (version 20.0 or higher)
  • npm (comes with Node.js)
  • Git (for cloning the repository)
  • Docker & Docker Compose (optional, for containerized development)

Getting Started​

Option 1: Local Development with Node.js​

1. Clone the Repository​

git clone https://gitlab.com/pixlr/docs.git
cd docs

2. Install Dependencies​

npm install

3. Start the Development Server​

npm run start

The site will automatically open in your browser at http://localhost:3000/

4. Make Your Changes​

  • Edit files in the docs/ directory
  • The site will automatically reload as you save changes
  • You'll see any build errors in the terminal

5. Build for Production​

npm run build

This generates a static site in the build/ directory.

Option 2: Docker Compose Development​

1. Clone the Repository​

git clone https://gitlab.com/pixlr/docs.git
cd docs

2. Start with Docker Compose​

docker-compose up

This will:

  • Build the Docker image
  • Install all dependencies
  • Start the development server
  • Expose the site at http://localhost:3000/

3. Make Your Changes​

  • Edit files in the docs/ directory
  • The site will automatically reload as you save changes
  • View logs in the terminal

4. Stop the Development Server​

docker-compose down

Project Structure​

docs/
├── docs/                    # Documentation files (Markdown)
│   ├── intro.md            # Introduction page
│   ├── contribute.md        # This file
│   └── analytics/          # Analytics documentation
├── blog/                   # Blog posts
├── src/
│   ├── components/         # React components
│   ├── css/               # Custom styling
│   └── pages/             # Custom pages
├── static/                # Static assets (images, logos)
├── docusaurus.config.ts   # Main configuration
├── sidebars.ts            # Sidebar navigation
└── package.json           # Dependencies

Available Commands​

CommandDescription
npm run startStart the development server
npm run buildBuild the site for production
npm run serveServe the production build locally
npm run clearClear the build cache
npm run typecheckCheck TypeScript types
npm run swizzleCustomize Docusaurus components

Writing Documentation​

Creating a New Document​

  1. Create a new .md or .mdx file in the docs/ directory
  2. Add frontmatter at the top:
---
sidebar_position: 3
---

# Your Document Title

Your content here...

Markdown Features​

  • Headings: Use #, ##, ###, etc.
  • Code blocks: Use triple backticks with language specification
  • Links: [text](url) or [text](/docs/path)
  • Images: ![alt text](image.png)
  • Tables: Use standard Markdown table syntax
  • Callouts: Use :::note, :::tip, :::warning, :::danger

Example:

:::tip
This is a helpful tip!
:::

:::warning
This is a warning!
:::

Styling & Theme​

The documentation uses:

  • Tailwind CSS for utility classes
  • Lucide React for icons
  • Custom CSS in src/css/custom.css

Color Palette​

  • Primary: Indigo (#6366f1)
  • Secondary: Purple (#8b5cf6)
  • Accent: Cyan (#06b6d4)
  • Dark Background: #1a1a2e
  • Light Background: #ffffff

Submitting Changes​

  1. Create a new branch for your changes:

    git checkout -b feature/your-feature-name

  2. Make your changes and commit:

    git add .
    git commit -m "Add your descriptive commit message"

  3. Push to your branch:

    git push origin feature/your-feature-name

  4. Create a Merge Request on GitLab

Troubleshooting​

Port 3000 Already in Use​

If port 3000 is already in use, you can specify a different port:

npm run start -- --port 3001

Build Errors​

Clear the cache and rebuild:

npm run clear
npm run build

Docker Issues​

Rebuild the Docker image:

docker-compose down
docker-compose build --no-cache
docker-compose up

Need Help?​

Happy contributing! 🚀