mirror of
https://github.com/imfing/hextra.git
synced 2025-10-31 02:24:53 -04:00
83f3b5052e
* chore(docs): rename `exampleSite` to `docs` and create `examples` * chore(build): update build script to support new version format and source directories; add v0.10 to documentation menu
111 lines
3.9 KiB
Markdown
111 lines
3.9 KiB
Markdown
# Contribute to Hextra
|
||
|
||
👋 Thank you for being interested in contributing to Hextra! As an open source project, we welcome contributions of many forms including bug reports, feature requests, documentation improvements, and code contributions.
|
||
|
||
<!-- omit in toc -->
|
||
## Table of Contents
|
||
|
||
- [Guidelines](#guidelines)
|
||
- [Contributing Code](#contributing-code)
|
||
- [Contributing Documentation](#contributing-documentation)
|
||
- [💬 GitHub Discussions](#-github-discussions)
|
||
- [GitHub Issues](#github-issues)
|
||
- [Development](#development)
|
||
- [Local development setup](#local-development-setup)
|
||
- [Project structure](#project-structure)
|
||
- [Start the development server](#start-the-development-server)
|
||
- [Compile the styles](#compile-the-styles)
|
||
|
||
|
||
## Guidelines
|
||
|
||
### Contributing Code
|
||
|
||
To contribute, please follow the ["Fork and Pull Request"][fork and pull] workflow：
|
||
|
||
Fork the repository, make your changes, and then submit a pull request.
|
||
Please make sure to include a description of the changes you made and why you made them.
|
||
Use [Conventional Commits][conventional commits] message to make it easier to understand the changes you made.
|
||
|
||
### Contributing Documentation
|
||
|
||
Similar to contributing code, you can also contribute to the documentation by submitting a pull request.
|
||
|
||
The documentation site is located in the [`docs`](../docs/) folder.
|
||
You can make changes to the documentation and create a pull request. A preview of the new documentation will be automatically generated and displayed in the pull request comment via [Netlify][netlify deploy preview].
|
||
|
||
### 💬 GitHub Discussions
|
||
|
||
We’re using [Discussions][discussions] as a place to connect with other members using Hextra:
|
||
|
||
- Ask questions you’re wondering about.
|
||
- Share ideas.
|
||
- Engage with other users.
|
||
|
||
### GitHub Issues
|
||
|
||
If you find a bug or have a feature request, please [open an issue][issues].
|
||
|
||
Please make sure to include a description of the bug or feature you are requesting. If you are reporting a bug, please include steps to reproduce the bug.
|
||
|
||
We recommend that you search existing [issues][issues] or discussions before opening a new one to prevent duplicates.
|
||
|
||
## Development
|
||
|
||
> **Note**
|
||
> You can start developing on [GitHub Codespaces][open in codespaces] or use [devcontainer][devcontainer] locally without installing any dependencies.
|
||
|
||
### Local development setup
|
||
|
||
- [Hugo][hugo] >= v0.124.0 (extended version)
|
||
- [Node.js][nodejs]
|
||
- [Go][go]
|
||
|
||
Install dependencies:
|
||
|
||
```bash
|
||
npm i
|
||
```
|
||
|
||
### Project structure
|
||
|
||
- [`assets`](../assets/): CSS styles and JavaScript files.
|
||
- [`data`](../data/): The theme data files. Now only contains the `icons.yaml` file.
|
||
- [`docs`](../docs/): The documentation site for the theme.
|
||
- [`i18n`](../i18n/): The theme translation files.
|
||
- [`layouts`](../layouts/): The theme layouts.
|
||
- [`static`](../static/): The static files for the theme. For example, the favicon and the site logo.
|
||
|
||
Please refer to the [Hugo documentation][hugo] for more information.
|
||
|
||
### Start the development server
|
||
|
||
```bash
|
||
npm run dev:theme
|
||
```
|
||
|
||
It starts the Hugo server on `http://localhost:1313/` for the `docs` content.
|
||
|
||
### Compile the styles
|
||
|
||
For development preview, we compile the Tailwind CSS styles on the fly. But for production, we need to compile the styles first.
|
||
|
||
```bash
|
||
npm run build:css
|
||
```
|
||
|
||
It will compile the Tailwind CSS styles and generate the `assets/css/compiled/main.css` file.
|
||
|
||
<!--links-->
|
||
|
||
[fork and pull]: https://docs.github.com/en/get-started/quickstart/contributing-to-projects
|
||
[conventional commits]: https://www.conventionalcommits.org
|
||
[issues]: https://github.com/imfing/hextra/issues
|
||
[discussions]: https://github.com/imfing/hextra/discussions
|
||
[nodejs]: https://nodejs.org/en/
|
||
[hugo]: https://gohugo.io/
|
||
[go]: https://golang.org/doc/install
|
||
[devcontainer]: https://code.visualstudio.com/docs/devcontainers/containers
|
||
[open in codespaces]: https://codespaces.new/imfing/hextra
|
||
[netlify deploy preview]: https://docs.netlify.com/site-deploys/deploy-previews/
|