diff --git a/README.md b/README.md index b8830917..1dddf4dd 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,46 @@ # ProperDocs -> *Project documentation with Markdown* - [![PyPI Version][pypi-v-image]][pypi-v-link] [![Build Status][GHAction-image]][GHAction-link] -ProperDocs is a **fast**, **simple** and **downright gorgeous** static site -generator that's geared towards building project documentation. Documentation -source files are written in Markdown, and configured with a single YAML -configuration file. It is designed to be easy to use and can be extended with -third-party themes, plugins, and Markdown extensions. +ProperDocs is a static site generator intended for project documentation. Source files are written in Markdown and converted to static HTML during the build process. + +Project configuration is defined in a YAML configuration file (`properdocs.yml`). This file specifies the documentation structure, theme configuration, and optional plugin settings. + +ProperDocs supports extension through plugins, themes and Markdown extensions. -Please see the [Documentation][properdocs] for an introductory tutorial and a full -user guide. +For usage instructions and examples, see the Documentation. + +--- ## Features -- Build static HTML files from Markdown files. -- Use Plugins and Markdown Extensions to enhance ProperDocs. -- Use third party themes or create your own. -- Publish your documentation anywhere that static files can be served. -- Much more! +Current functionality includes: + +- Conversion of Markdown source files into static HTML pages +- YAML-based configuration +- Plugin system for extending functionality +- Support for Markdown extensions +- Support for third-party themes +- Static output suitable for deployment on standard web servers + +Additional functionality is available through plugins. + +--- ## Support -If you need help with ProperDocs, do not hesitate to get in contact with us! +If you encounter problems while using ProperDocs, the following resources are available: - For questions and high-level discussions, use **[Discussions]** on GitHub. - For small questions, a good alternative is the **[Discord server]**. - To report a bug or make a feature request, open an **[Issue]** on GitHub. -Please note that we may only provide -support for problems/questions regarding core features of ProperDocs. Any -questions or bug reports about features of third-party themes, plugins, -extensions or similar should be made to their respective projects. -But, such questions are *not* banned from the [chat room]. +Support is generally limited to **core ProperDocs functionality**. Issues related to third-party themes, plugins or extensions should normally be reported to the maintainers of those projects. + +Questions about such components may still be discussed in chat. -Make sure to stick around to answer some questions as well! +--- ## Links @@ -44,22 +48,32 @@ Make sure to stick around to answer some questions as well! - [Latest Release Notes][release-notes] - [Catalog of third-party plugins, themes and recipes][catalog] -## Contributing to ProperDocs +--- + +## Contributing + +Contributions are welcome. -The ProperDocs project welcomes, and depends on, contributions from developers and -users in the open source community. Please see the [Contributing Guide] for -information on how you can help. +For development setup, coding guidelines and contribution workflow, see the **[Contributing Guide]**. + +--- ## Code of Conduct -Everyone interacting in the ProperDocs project's codebases, issue trackers, and -discussion forums is expected to follow the [PyPA Code of Conduct]. +All participants in the ProperDocs project are expected to follow the **[PSF Code of Conduct]**. + +--- + +## License + +ProperDocs is distributed under the [**BSD-2-Clause license**](LICENSE). [pypi-v-image]: https://img.shields.io/pypi/v/properdocs.svg [pypi-v-link]: https://pypi.org/project/properdocs/ [GHAction-image]: https://github.com/properdocs/properdocs/actions/workflows/ci.yml/badge.svg [GHAction-link]: https://github.com/properdocs/properdocs/actions/workflows/ci.yml + [properdocs]: https://properdocs.org [Issue]: https://github.com/properdocs/properdocs/issues @@ -67,9 +81,5 @@ discussion forums is expected to follow the [PyPA Code of Conduct]. [Discord server]: https://discord.gg/CwYAgEPHZd [release-notes]: https://properdocs.org/about/release-notes/ [Contributing Guide]: https://properdocs.org/about/contributing/ -[PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/ +[PSF Code of Conduct]: https://www.python.org/psf/conduct/ [catalog]: https://github.com/properdocs/catalog - -## License - -[BSD-2-Clause](https://github.com/properdocs/properdocs/blob/master/LICENSE)