Skip to content

Markdown Docs Kit

GitHub Release GitHub Release Date GitHub commits since latest release Libraries.io dependency status for GitHub repo Issues Maintained License: CC BY 4.0

Project Overview 🚀

This repository contains common documentation files that can be reused across multiple projects to maintain consistency and streamline the setup process.

Current Contents

  • .github/FUNDING.yml: Information on funding options and sponsorship links.
  • .github/PULL_REQUEST_TEMPLATE.md: Default pull request template for general contributions.
  • .github/PULL_REQUEST_TEMPLATE/*: Templates for specific pull requests, such as bugfix, docs, and feature.
  • .github/ISSUE_TEMPLATE/*: Templates for reporting bugs, requesting features, and asking questions.
  • CODE_OF_CONDUCT.md: Standards for behavior within the community.
  • CONTRIBUTING.md: Guidelines on how to contribute to the project.
  • README.md: A general template for project README, outlining setup instructions, usage, and contribution guidelines.
  • SCHOOL_PROJECT_README.md: A specialized README template for educational or school-related projects.
  • SECURITY.md: Guidelines for securely reporting vulnerabilities and related contact details.
  • STYLEGUIDE.md: Coding and documentation conventions for consistency and maintainability.

Prerequisites ⚙️

Make sure the following tools are installed on your system:

Usage 🛠️

Run the Deployment Script

Execute the deploy.sh script to download the latest documentation and apply configurations:

bash deploy.sh --target <target_directory> [--config <path_to_config.yml>]

Options:

  • --target <target_directory>: Specifies where the documentation will be deployed.
  • --config <path_to_config.yml> (optional): Path to a custom configuration file. Defaults to config.yml in the current directory.
  • Additionally, you can override repository details using --repo-owner and --repo-name if necessary.

Manual Setup (Optional)

If you prefer, manually clone the repository and copy the required documentation files:

git clone https://github.com/Jekwwer/markdown-docs-kit.git

Then customize the necessary files for your project.

Example Deployment

To deploy documentation to a new repository:

bash deploy.sh --target ../my-new-repo

This will:

  • Fetch the latest release.
  • Replace placeholders using config.yml.
  • Deploy files to ../my-new-repo, maintaining the folder structure.

Potential Future Documents 📜

This table serves as a reference for adding new documents to meet future project requirements as they arise.

Document Name Purpose
ACKNOWLEDGMENTS.md Recognizes contributions from libraries, frameworks, or individuals.
ARCHITECTURE.md Offers an overview of the project’s structure and design decisions.
BUILD.md Instructions for building the project, including dependencies and troubleshooting.
CONFIG.md Documents configuration options, environment variables, and setup instructions.
CONTRIBUTING.md Guidelines for contributing to the project: coding standards, PRs, and issue reports.
CONVENTIONS.md Describes naming patterns, coding standards, or folder structures for consistency.
DEPENDENCIES.md Lists key dependencies and their versions for compatibility insights.
FAQ.md Answers frequently asked questions to save time and clarify common concerns.
GLOSSARY.md Defines domain-specific terms and abbreviations for clarity.
GOVERNANCE.md Outlines roles, responsibilities, and decision-making processes for maintainers.
INSTALL.md Detailed installation instructions for projects with complex setup requirements.
MIGRATION_GUIDE.md Helps users upgrade between major versions by detailing changes and migration steps.
ROADMAP.md Provides insights into the project’s future direction and priorities.
RELEASE.md Instructions for managing and packaging project releases.
SUPPORT.md Provides resources for getting help, including forums, FAQs, or troubleshooting guides.
TESTING.md Explains testing frameworks, setup, and commands for running tests.
TODO.md Lists future plans, pending features, or unresolved issues for transparency.
USAGE.md Advanced usage examples, command-line options, or API details.

Contributing 👥

Contributions are welcome! Please read the Contributing Guidelines and check the Issues page.

License 🛡️

This repository is licensed under Creative Commons Attribution 4.0 (CC BY 4.0) for the Markdown templates located in the templates/ directory. You must provide attribution when using them (see LICENSE).

The development environment (scripts, configuration, and tooling) is based on markdown-workspace and is licensed under MIT (see MIT-LICENSE).

Contact 📬

For questions, reach out via evgenii.shiliaev@jekwwer.com or open an issue.

Notes

This repository is synchronized with the Markdown Workspace, currently at version v1.6.0. The repository serves as a development foundation for working on markdown documentation effectively.

This document is based on a template by Evgenii Shiliaev, licensed under CC BY 4.0. All additional content is licensed under MIT.