Contributing to Bluefin Documentation#

Thank you for contributing to the Bluefin documentation! This guide covers how to contribute to this documentation repository specifically.

Good First Contributions#

New to contributing? Here are some great ways to get started:

• Fix a broken or outdated link — If you find a link that no longer works or points to old information, submit a fix.
• Add a missing step to an existing guide — If a guide assumes prior knowledge or skips a step, fill in the gap.
• Improve code block language tags — Ensure every code block has a language tag (e.g., bash, yaml, json) for proper syntax highlighting.
• Check issues labeled "good first issue" — We tag beginner-friendly issues to help you find a place to start.

If something confused you, it probably confuses others too. Don't hesitate to open an issue or PR for anything unclear.

Content Scope#

What Belongs Here#

• Bluefin-specific features, workflows, and customizations
• Integration guides (Homebrew, Flatpak, distrobox usage on Bluefin)
• Getting started guides and installation instructions
• Community-specific information (values, mission, FAQ)

What Belongs Upstream#

Prefer linking to upstream documentation with a brief summary rather than duplicating content.

Link to upstream docs for:

• General Linux/GNOME usage
• Flatpak, Podman, or distrobox documentation
• Upstream Fedora or Universal Blue features
• Third-party application documentation

Example: Instead of documenting how to use VSCode, link to VSCode's official docs and note any Bluefin-specific setup (like using it in a dev container).

Style Guide#

Tone#

• Conversational and welcoming: Think "helpful friend" not "technical manual"
• Concise: Bluefin docs are intentionally sparse—keep it scannable
• Assume competence: Our audience includes developers and power users

Document Structure#

• Use frontmatter with title and optional slug:
  ⧉

  ---
  title: Your Page Title
  slug: /your-slug
  ---
  

• One H1 (#) per page (typically the title)
• Start sections with H2 (##), subsections with H3 (###)
• Use tip/info/warning admonitions for callouts:
  ⧉

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

Code Blocks#

• Always specify the language for syntax highlighting:
  ⧉

  ```bash
  rpm-ostree status
  ```
  

• Use bash for shell commands, yaml for configs, json for JSON, etc.
• For multi-line commands, use \ for line continuation

Links#

• Prefer absolute paths for internal docs: /introduction not ./introduction.md
• Use descriptive link text: [install Homebrew](/command-line) not [click here](link)

Contribution Workflow#

1. Fork and clone#

1. Click Fork on the repository page.
2. Clone your fork:
   ⧉

   git clone https://github.com/<your-username>/documentation.git
   cd documentation
   

3. Add the upstream remote:
   ⧉

   git remote add upstream https://github.com/projectbluefin/documentation.git
   

2. Create a branch#

Always branch from main:

git checkout main
git pull upstream main
git checkout -b docs/my-improvement

Branch naming conventions:

3. Make your changes#

Edit or create .md or .mdx files in docs/. Follow the Style Guide below.

Preview your changes locally:

npm install --legacy-peer-deps
npm start

The site will be available at http://localhost:3000.

4. Commit and push#

Run Prettier before committing (required):

npm run prettier

Then commit and push:

git add .
git commit -m "docs: describe your change"
git push origin docs/my-improvement

Commit message format: <type>: <short description> (e.g., docs: add nvidia driver guide, fix: correct broken link in FAQ).

5. Open a pull request#

Go to your fork on GitHub and click Compare & pull request. Fill in the template, reference any related issues with Fixes #<number>, and submit.

Local Development#

Prerequisites#

• Node.js 20+
• npm

Setup#

# Install dependencies (required due to peer dependency conflicts)
npm install --legacy-peer-deps

# Start development server
npm run start

The site will be available at http://localhost:3000.

Using Just (Optional)#

just serve # Build and serve locally
just build # Build only

Using Docker (Alternative)#

docker compose up

Contribution Workflow#

New to open source? Here's the full flow from fork to merged PR.

1. Fork and clone#

1. Click Fork on the documentation repo to get your own copy.
2. Clone your fork locally:

git clone https://github.com/<your-username>/documentation.git
cd documentation

3. Add the upstream remote so you can pull in future changes:

git remote add upstream https://github.com/projectbluefin/documentation.git

2. Create a branch#

Always work on a feature branch — never commit directly to main:

git checkout -b docs/my-change

Use a short, descriptive name that reflects the change: docs/fix-broken-links, docs/add-homebrew-guide, docs/update-installation-steps.

3. Make your changes#

Edit or create .md / .mdx files in docs/, blog/, or wherever is appropriate. Preview locally (npm run start) as you go.

4. Format and check#

npm run prettier # REQUIRED before every commit
npm run start # verify the page renders correctly

5. Commit and push#

git add .
git commit -m "docs: brief description of what you changed"
git push origin docs/my-change

6. Open a pull request#

Go to your fork on GitHub and click Compare & pull request. Fill in the PR template: explain what changed and why, and reference any related issue with Fixes #N or Related to #N.

Keeping your fork up to date#

Before starting a new branch, sync with upstream to avoid conflicts:

git fetch upstream
git checkout main
git merge upstream/main

Before Submitting#

Format Your Changes#

REQUIRED: Run Prettier before submitting your PR:

npm run prettier

This formats all files according to the project's style (80-char width, 2-space indent, LF line endings).

Check Your Changes#

• Preview locally to ensure formatting looks correct
• Verify links work (internal and external)
• Check that code blocks render with proper syntax highlighting

Pull Request Process#

1. Create a descriptive PR title: docs: add installation guide for Nvidia drivers
2. Reference related issues: Fixes #123 or Related to #456
3. Keep PRs focused: One topic per PR when possible
4. Expect feedback: Reviewers may suggest content placement or style changes

What Reviewers Look For#

• Content placement: Does this belong here or upstream?
• Tone consistency: Does it match the conversational Bluefin style?
• Prettier compliance: Are files formatted correctly?
• Link validity: Do all links work?
• Clarity: Is it scannable and easy to understand?

Adding a New Doc Page#

1. Create your .md or .mdx file in the docs/ directory
2. Add frontmatter with title and optional slug
3. Update sidebars.ts if you want it in the navigation
4. Follow the style guide above
5. Run npm run prettier before committing

Questions?#

• Open a discussion for questions
• Check existing issues for known topics
• See the main Contributor's Guide for broader project contribution info
• To contribute translations, see TRANSLATING.md

Remember: There's likely a reason why something is undocumented. When in doubt, link to upstream docs!