diff --git a/README.md b/README.md index 1f001fed..b3520a64 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,44 @@ -# ProperDocs +## ProperDocs -> *Project documentation with Markdown* +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. -[![PyPI Version][pypi-v-image]][pypi-v-link] -[![Build Status][GHAction-image]][GHAction-link] +Project configuration is defined in a YAML configuration file (in `properdocs.yml`). This file specifies documentation structure, theme configuration, and optional plugin settings. -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 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 the built-in themes, 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 +* Built-in themes +* Support for third-party themes +* Static output suitable for deployment on standard web servers + +Additional functionality may be 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 **[Chat room]** on - Gitter/Matrix. +- For small questions, a good alternative is the **[Chat room]** on Gitter/Matrix. - 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 @@ -45,16 +46,25 @@ 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 -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. +Contributions are welcome. + +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 **PyPA Code of Conduct**. + +--- + +## License + +ProperDocs is distributed under the **BSD-2-Clause license**. [pypi-v-image]: https://img.shields.io/pypi/v/properdocs.svg