# Community Files

Open-source projects rely on more than just code. Files like `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md` set expectations for how people participate in and interact with a project. Most projects already have these files, but they often sit in the repository root where casual users never see them.

Great Docs automatically detects these standard community files and turns them into styled pages on your documentation site. Each detected file gets its own page and a link in the **Community** section of the homepage's right sidebar. No configuration is needed. If the file exists, it becomes part of your site.


# Supported Files

Great Docs recognizes the following community files:

| File | Generated Page | Sidebar Link |
|----|----|----|
| `CONTRIBUTING.md` | `contributing.qmd` | "Contributor guidelines" |
| `CODE_OF_CONDUCT.md` | `code-of-conduct.qmd` | "Code of conduct" |
| `ROADMAP.md` New in 0.2 | `roadmap.qmd` | "Project roadmap" |
| `SECURITY.md` New in 0.3 | `security.qmd` | "Security policy" |
| `CITATION.cff` | `citation.qmd` | "Citing *package*" |

These files follow the common conventions used by most open-source projects, so if you already have them, they'll work automatically.


# How It Works

During `great-docs build`, each community file goes through a simple pipeline:

1.  **Detects the file** in your project root (and `.github/` as a fallback)
2.  **Strips the title** by removing the first `#` heading line (since Great Docs adds its own title via frontmatter)
3.  **Generates a `.qmd` file** in the build directory with appropriate frontmatter
4.  **Adds a sidebar link** in the Community section of the homepage's right margin

The original Markdown content is preserved, so any formatting, images, or links in your community files carry through to the documentation site. The generated `.qmd` files are recreated on every build, so changes to the source files are always picked up.


# Example

To see how everything comes together, consider a project with these files:

    my-package/
    ├── .github/
    │   └── SECURITY.md
    ├── CONTRIBUTING.md
    ├── CODE_OF_CONDUCT.md
    ├── ROADMAP.md
    ├── great-docs.yml
    └── pyproject.toml

Will produce a homepage sidebar like:

    Community
    ├── Contributor guidelines
    ├── Code of conduct
    ├── Project roadmap
    ├── Security policy

Clicking any link navigates to the corresponding page. If any of these files are missing, the corresponding link is simply omitted.


# ROADMAP.md New in 0.2

A `ROADMAP.md` file communicates your project's future direction to users and contributors. This helps potential contributors understand where they can have the most impact and gives users confidence that the project is actively maintained. Common sections include:

- **In Progress**: features currently being developed
- **Near Term**: planned for the next release cycle
- **Medium Term**: targeted for upcoming major versions
- **Long Term**: aspirational features on the horizon


## Example Structure

``` markdown
# Roadmap

A summary of planned features and improvements.

## In Progress

### Feature Name
Brief description...

## Near Term

### Feature Name
Brief description...

## Long Term

### Feature Name
Brief description...
```

> **Tip: Keep it forward-looking**
>
> Focus on unshipped features. Shipped features are better documented in your Changelog (auto-generated from GitHub Releases) or release notes.


# CONTRIBUTING.md

A clear `CONTRIBUTING.md` lowers the barrier for new contributors. Without one, people who want to help may not know where to start or what process to follow. Common sections include:

- development setup instructions
- how to run tests
- code style guidelines
- pull request process
- issue reporting guidelines


## Example Structure

``` markdown
# Contributing

We welcome contributions! Here's how to get started.

## Development Setup

1. Clone the repo
2. Install dependencies: `pip install -e ".[dev]"`
3. Run tests: `pytest`

## Pull Request Process

1. Fork the repo and create a branch
2. Make your changes with tests
3. Submit a PR describing your changes
```


# SECURITY.md New in 0.3

A `SECURITY.md` file tells users how to responsibly report security vulnerabilities. Without one, people who discover a vulnerability may open a public issue, exposing the problem before a fix is available. GitHub also recognizes this file and displays it under the **Security** tab of your repository.

Great Docs looks for `SECURITY.md` in two locations (in order):

1.  project root (`SECURITY.md`)
2.  `.github/` directory (`.github/SECURITY.md`)


## Example Structure

``` markdown
# Security Policy

## Reporting a Vulnerability

Please do not open a public issue. Instead, use the
Report a vulnerability function on the Security tab.

Your report should include:

- a clear description of the vulnerability
- steps to reproduce the issue
- any relevant code snippets or proof-of-concept

## Coordinated Disclosure

Once confirmed, we will notify you before public disclosure
and credit you in the release notes.
```


## Disabling the Security Page

To detect `SECURITY.md` but not generate a page for it, set `show_security: false` in `great-docs.yml`:

``` yaml
site:
  show_security: false
```


# CODE_OF_CONDUCT.md

A code of conduct sets expectations for community behavior and signals that your project takes a welcoming environment seriously. Most projects adopt a standard like the [Contributor Covenant](https://www.contributor-covenant.org/) rather than writing one from scratch.


## Using the Contributor Covenant

Download version 2.1 from the official site:

``` bash
curl -o CODE_OF_CONDUCT.md https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md
```

Then customize the contact email at the bottom of the file.


# CITATION.cff

If your project has a `CITATION.cff` file, Great Docs generates a dedicated citation page (`citation.qmd`) and adds a "Citing *package*" link to the Community sidebar. The generated page includes a formatted author list, a text citation, and a BibTeX entry, all derived from the structured data in the CFF file.

The `CITATION.cff` file is only used for the citation page. Author information displayed elsewhere on the site (such as the Developers section of the homepage sidebar) comes from `great-docs.yml` first, with `pyproject.toml` as a fallback.


## Example Structure


    CITATION.cff


``` yaml
cff-version: 1.2.0
title: "My Package"
message: "If you use this software, please cite it as below."
type: software
authors:
  - family-names: Smith
    given-names: Jane
    orcid: "https://orcid.org/0000-0002-1234-5678"
version: 1.0.0
date-released: "2025-06-15"
license: MIT
repository-code: "https://github.com/example/my-package"
```


If a `repository-code` or `url` field is present, the citation page links back to the `CITATION.cff` file on GitHub.


# `.github/` Directory Fallback

For `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md`, Great Docs checks the `.github/` directory if the file isn't found in the project root. This matches GitHub's own convention for repository-level community health files, so projects that follow the GitHub standard layout work without changes.


# Fallback Behavior

If a community file doesn't exist, the build continues without error. The corresponding link simply won't appear in the sidebar. You can add community files at any time and they'll be automatically detected on the next build. This means you can introduce community files gradually as your project matures.


# Package Info

In addition to community files, Great Docs automatically generates a **Package Info** page that displays your package's declared dependencies. This page surfaces important metadata about what your package requires to run and what optional components are available.


## What It Shows

The Package Info page includes:

- runtime Dependencies: packages required to use your library (from `dependencies` in `pyproject.toml`)
- optional Dependencies: extra packages grouped by feature (from `optional-dependencies`)
- version Constraints: specifier ranges for each package (e.g., `>=1.24`, `>=2.0,<3.0`)
- environment Markers: platform or Python version constraints (e.g., `python_version<'3.12'`)
- last Published: the latest release date of each dependency on PyPI
- PyPI Link: direct links to the PyPI page for each package

Dependencies are presented in tables with one group per optional dependency set (e.g., `dev`, `docs`, `test`).


## Configuration

The Package Info page is enabled by default. To disable it, add to `great-docs.yml`:


    great-docs.yml


``` yaml
package_info_page: false
```


## Accessing the Page

The Package Info page is accessible via a "Package Info" link in the **Meta** section of the homepage sidebar (next to "Requires", "Provides-Extra", and "Site Tags"). The page is located at `package-info.html` and is also included in your site's navigation and search index.


## When To Use It

This feature is useful for:

- users evaluating your package's compatibility with their environment
- CI/CD pipelines checking dependency requirements
- developers understanding what optional features are available
- dependency scanners and compliance tools


# Next Steps

Community files give your project a professional, welcoming presence without any configuration. Adding a `CONTRIBUTING.md` or `CODE_OF_CONDUCT.md` to your repository is all it takes to get a styled page in your documentation site.

- [Changelog](changelog.md) covers auto-generating a changelog from GitHub Releases
- [Linting](linting.md) helps you catch broken links and other issues in community file pages
- [SEO & Metadata](seo.md) explains how community pages are included in site metadata
- [Configuration](configuration.md) covers all `great-docs.yml` options