Managing sources.json Files

Understanding OpenGround’s source configuration system and priority order

Overview

OpenGround uses sources.json files to store library source configurations. This allows you to add documentation by name alone, without repeatedly specifying URLs and options.

How Sources Files Work

When you add documentation with the --source flag, OpenGround automatically saves the configuration so you can reference it by name later.

1. First time: Add with full configuration

   openground add fastapi \
     --source https://github.com/tiangolo/fastapi.git \
     --docs-path docs/ \
     -y
   
2. Configuration is saved automatically

   OpenGround saves to ~/.openground/sources.json:

   {
     "fastapi": {
       "type": "git_repo",
       "repo_url": "https://github.com/tiangolo/fastapi.git",
       "docs_paths": ["docs/"]
     }
   }
   
3. Later: Use name only

   # Uses saved configuration
   openground add fastapi --version v0.110.0 -y
   

Types of Sources Files

OpenGround supports multiple sources files with a priority system:

1. User Sources File

Location: ~/.openground/sources.json

• Shared across all your projects
• Created automatically when you first use --source
• Default location for auto-saved sources

2. Project Sources File

Location: .openground/sources.json (in project directory)

• Project-specific overrides
• Takes priority over user sources
• Useful for project-specific documentation versions

3. Custom Sources File

Location: Anywhere you specify

• Specified via --sources-file flag
• Takes highest priority
• Useful for team-shared configurations

4. Package-Level Sources

Location: Inside OpenGround package

• Bundled default sources
• Lowest priority (fallback)

Priority Order

When looking up a library by name, OpenGround checks in this order:

1. 1. Custom path via --sources-file

   openground add mylib --sources-file /team/shared/sources.json -y
   

   Highest priority - explicitly specified.

2. 2. Project-local .openground/sources.json

   Located in current directory’s .openground/ folder.

   Allows project-specific overrides.

3. 3. User ~/.openground/sources.json

   Your personal sources file.

   Shared across all projects.

4. 4. Package-level bundled sources

   Default sources included with OpenGround.

   Lowest priority (fallback only).

Sources File Structure

The sources.json file maps library names to their configurations:

Git Repository

{
  "fastapi": {
    "type": "git_repo",
    "repo_url": "https://github.com/tiangolo/fastapi.git",
    "docs_paths": ["docs/"]
  },
  "pytorch": {
    "type": "git_repo",
    "repo_url": "https://github.com/pytorch/pytorch.git",
    "docs_paths": ["docs/", "tutorials/"]
  }
}

Source Type Fields

Git Repository ("type": "git_repo")

{
  "library-name": {
    "type": "git_repo",
    "repo_url": "https://github.com/user/repo.git",
    "docs_paths": ["docs/", "wiki/"]  // Optional
  }
}

Fields:

• type - Must be "git_repo"
• repo_url - Git repository URL (required)
• docs_paths - Array of paths within repo (optional, defaults to entire repo)
• languages - Array of programming languages (optional, metadata only)

Sitemap ("type": "sitemap")

{
  "library-name": {
    "type": "sitemap",
    "sitemap_url": "https://docs.example.com/sitemap.xml",
    "filter_keywords": ["docs", "api"]  // Optional
  }
}

Fields:

• type - Must be "sitemap"
• sitemap_url - URL to XML sitemap (required)
• filter_keywords - Array of URL filters (optional)
• languages - Array of programming languages (optional, metadata only)

Local Path ("type": "local_path")

{
  "library-name": {
    "type": "local_path",
    "local_path": "~/projects/library/docs"
  }
}

Fields:

• type - Must be "local_path"
• local_path - Path to local directory (required)
• languages - Array of programming languages (optional, metadata only)

Auto-Save Behavior

By default, OpenGround automatically saves sources to ~/.openground/sources.json when you use --source:

# This automatically saves the configuration
openground add fastapi \
  --source https://github.com/tiangolo/fastapi.git \
  --docs-path docs/ \
  -y

# Success message confirms:
# "Added source for 'fastapi' to ~/.openground/sources.json"

Disable Auto-Save

To disable automatic source saving:

openground config set sources.auto_add_local false

Now sources will only be saved if you manually edit the file.

Re-enable Auto-Save

openground config set sources.auto_add_local true

Project-Specific Overrides

Use project-local sources files to override user sources for specific projects:

1. Create project sources directory

   mkdir -p .openground
   
2. Create project sources.json

   cat > .openground/sources.json << 'EOF'
   {
     "fastapi": {
       "type": "git_repo",
       "repo_url": "https://github.com/tiangolo/fastapi.git",
       "docs_paths": ["docs/", "tutorial/"]
     }
   }
   EOF
   
3. Use in project

   # In this project, uses project-specific config
   openground add fastapi -y
   
   # Outside this project, uses ~/.openground/sources.json
   

Custom Sources File

Share a sources file across a team:

# Create team sources file
cat > /team/shared/sources.json << 'EOF'
{
  "internal-api": {
    "type": "git_repo",
    "repo_url": "https://github.com/company/internal-api.git",
    "docs_paths": ["docs/"]
  },
  "design-system": {
    "type": "sitemap",
    "sitemap_url": "https://design.company.com/sitemap.xml"
  }
}
EOF

# Use custom sources file
openground add internal-api --sources-file /team/shared/sources.json -y

Set Default Custom Sources

Configure OpenGround to always use a custom sources file:

# Set in config
openground config set sources.file_path /team/shared/sources.json

# Now this uses the custom file by default
openground add internal-api -y

# View current setting
openground config get sources.file_path

Viewing Sources Files

View User Sources

cat ~/.openground/sources.json

View Project Sources

cat .openground/sources.json

View Which File Is Used

When you run add with an existing source, OpenGround shows which file it’s using:

openground add fastapi -y

# Output includes:
# "Using sources file: /home/user/.openground/sources.json"

Editing Sources Files

Manual Editing

You can directly edit the JSON file:

# Edit user sources
vim ~/.openground/sources.json

# Edit project sources
vim .openground/sources.json

Adding a New Source Manually

{
  "existing-lib": {
    "type": "git_repo",
    "repo_url": "https://github.com/example/existing.git"
  },
  // Add new entry:
  "new-lib": {
    "type": "sitemap",
    "sitemap_url": "https://newlib.dev/sitemap.xml",
    "filter_keywords": ["docs"]
  }
}

Modifying Existing Source

{
  "fastapi": {
    "type": "git_repo",
    "repo_url": "https://github.com/tiangolo/fastapi.git",
    // Add or modify docs_paths:
    "docs_paths": ["docs/", "tutorial/", "advanced/"]
  }
}

Examples

Team Workflow

# Team lead creates shared sources
cat > /team/sources.json << 'EOF'
{
  "company-api": {
    "type": "git_repo",
    "repo_url": "https://github.com/company/api.git",
    "docs_paths": ["docs/"]
  },
  "design-system": {
    "type": "local_path",
    "local_path": "/shared/design-docs"
  }
}
EOF

# Team members configure their OpenGround
openground config set sources.file_path /team/sources.json

# Everyone can now use:
openground add company-api -y
openground add design-system -y

Multi-Project Developer

# Global sources for common libraries
cat > ~/.openground/sources.json << 'EOF'
{
  "fastapi": {
    "type": "git_repo",
    "repo_url": "https://github.com/tiangolo/fastapi.git",
    "docs_paths": ["docs/"]
  }
}
EOF

# Project A: Override with older version config
cd ~/projects/project-a
mkdir -p .openground
cat > .openground/sources.json << 'EOF'
{
  "fastapi": {
    "type": "git_repo",
    "repo_url": "https://github.com/tiangolo/fastapi.git",
    "docs_paths": ["docs_src/"]
  }
}
EOF

# In project-a: Uses project-specific config
openground add fastapi --version v0.95.0 -y

# In project-b: Uses global config
cd ~/projects/project-b
openground add fastapi --version v0.110.0 -y

Personal + Team Sources

# Personal sources for public libraries
cat > ~/.openground/sources.json << 'EOF'
{
  "numpy": {
    "type": "sitemap",
    "sitemap_url": "https://numpy.org/doc/sitemap.xml",
    "filter_keywords": ["docs/"]
  }
}
EOF

# Use team sources for company libraries
openground add internal-api \
  --sources-file /team/sources.json \
  -y

# Use personal sources for public libraries
openground add numpy -y

Troubleshooting

Library Not Found

If OpenGround can’t find a library:

# Check which file is being used
ls -la ~/.openground/sources.json
ls -la .openground/sources.json

# View contents
cat ~/.openground/sources.json | jq

# Verify library name matches exactly (case-sensitive)

Wrong Source Being Used

Check the priority order:

# Project sources override user sources
cat .openground/sources.json

# Remove project override if needed
rm .openground/sources.json

Invalid JSON

If you get JSON parse errors:

# Validate JSON
jq . ~/.openground/sources.json

# Common issues:
# - Missing comma between entries
# - Trailing comma on last entry
# - Unquoted keys
# - Single quotes instead of double quotes

Auto-Save Not Working

Check if auto-save is enabled:

# Check setting
openground config get sources.auto_add_local

# Should output: true
# If false, enable it:
openground config set sources.auto_add_local true

Best Practices

1. Use user sources for personal libraries - Keep frequently used libraries in ~/.openground/sources.json

2. Use project sources for project-specific versions - Override in .openground/sources.json when needed

3. Share team sources via config - Point sources.file_path to a shared location

4. Keep sources.json in version control - Commit .openground/sources.json to share with team

5. Document custom sources - Add comments in README about custom sources setup

# Example: Add to project README.md
echo '## Documentation Setup' >> README.md
echo 'To use this project with OpenGround:' >> README.md  
echo '```bash' >> README.md
echo 'openground add myproject -y' >> README.md
echo '```' >> README.md