# Contributing Guide

> How to contribute to "typedoc-plugin-markdown" and associated packages.

## Contents

* [Introduction](#introduction)
* [Contributing to the public docs](#contributing-to-the-public-docs)
* [Contributing to the codebase](#contributing-to-the-codebase)
  * [Getting Started](#getting-started)
* [Submitting a PR](#submitting-a-pr)
* [Acknowledgements](#acknowledgements)

## Introduction

Thank you for showing interest in contributing to this project. This guide provides some guidelines for doing so.

If something does not make sense please do not hesitate to ask for help in
[GitHub Discussions](https://github.com/typedoc2md/typedoc-plugin-markdown/discussions/categories/help).

## Contributing to the public docs

Contributions to the public facing documentation hosted at https://typedoc-plugin-markdown.org are welcome.

The site is built on [Nextra](https://nextra.site/docs) and you can edit the MDX
files located in the [docs folder](https://github.com/typedoc2md/typedoc-plugin-markdown/tree/main/docs)
of the repo.

Please note that the API docs (`/pages/api-docs`) are autogenerated and should
not be edited from that location.

When submitting a PR please use commit message in the format
`chore(docs): my docs update xxx`.

## Contributing to the codebase

### Getting Started

#### 1. Fork and clone the repository

Start by forking the repository to your own GitHub account. Then, clone the repository to your local machine. Please replace `<your-username>` with your actual GitHub username.

```bash
git clone git@github.com:<your-username>/typedoc-plugin-markdown.git
```

#### 2. Install dependencies

Navigate to the repository root and install the necessary dependencies:

```bash
cd typedoc-plugin-markdown

npm install
```

#### 3. Build the packages and run tests

Finally, you can build all the packages and run the tests to ensure everything is set up correctly.

Build all packages in the workspace:

```bash
npm run build-all
```

Test all packages in the workspace:

```bash
npm run test-all
```

If the project builds and the tests run successfully you are ready to start contributing to the project.

Please have a look at the codebase and follow documentation comments and
provided internal docs.

## Submitting a PR

Name your branch after the issue it addresses - `fix/<issue>-<slug>` for bug
fixes, `feature/<issue>-<slug>` for enhancements (for example
`fix/881-prettier-editorconfig`). If there is no associated issue, use
`chore/<slug>`.

Once you're ready to submit your changes:

* **Push your branch**: Push your branch to your forked repository on GitHub.
* **Create a PR**: Navigate to the original repository and create a PR from your branch to the main branch.
* **Provide a clear description**: Include a detailed description of your changes, why they're necessary, and any issues they resolve.
* **Link to relevant issues**: If your PR addresses any open issues, mention them in the description - as `Refs #123` rather than `Closes #123`. Issues are closed once the change is published to npm, so please avoid the `Closes`/`Fixes`/`Resolves` keywords that make GitHub close them on merge.

Please note we follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages.

The commit message should be in the form:

`fix(core): my bug fix xxx (#100)`

The scope should be one of `'core'`, `'frontmatter'`, `'remark'`, `'docusaurus'`, `'vitepress'`, `'githubwiki'`, `'gitlabwiki'`, `'docs'`.
Use `'core'` to contribute to the main project.

## Acknowledgements

Thank you to all the people who have already contributed to typedoc-plugin-markdown.