About docs-template

This docs-template provides a starting point for creating project documentation using Docusaurus 2 and Tailwind CSS. This README covers how to use the template, contribute to its development, and follow best practices.

Features

• TailwindCSS integration
• Dark-mode
• Mobile & desktop ready
• Optional integrations:
  • Algolia search
  • Google Tag Manager
  • Google Analytics

Initial structure

• No homepage
• No footer
• Social links and other useful Usher links at the navigation bar

How to use the template

1. Use the repository as a GitHub template — RECOMMENDED, or
2. Download and extract the ZIP file, or
3. Perform a shallow clone to create a new project without inheriting the template's Git history.

Conveniently, most parts of this template that needs to be changed are accompanied by an INITIAL TODO comment. Read this README before, then find them all on your project to change accordingly.

Example:

{ 
	// ...
	title: "My Usher Site", // INITIAL TODO
	// ...
}

Guide on how to customize this template

For further instructions on how to customize this template, we've provided a guide inbuilt in this repository. You'll be able to see it by running it and navigating to http://localhost:3000 or the URL you chose to deploy it.

Contributing to the Template

We encourage you to contribute by:

Proposing

• Components that are useful for many documentation projects.
• Improvements to the configuration for better usability.
• Better comments to make our default tooling more accessible.

Reporting

• Poor DX or any other issues that cause friction.
• Bug reports.

---

Below here is a basic structure to maintain at your docs README

---

📖 Welcome to {project} Documentation repository

This is the home of {project} docs! Here, we aim to help our users make the best of it, so they may {brief explanation of what the project helps them achieve}.

{don’t forget to link the original project repository, if it exists}

This website is built using Docusaurus 2, a static website generator.

Get started

Installation

$ pnpm install

Local Development

$ pnpm start

This command starts a local development server and opens a browser window. Most changes are reflected live without having to restart the server.

Customization

Creating and organizing content

• Store content in the docs directory, supporting .md and .mdx files. Learn more →
• Configure each folder metadata accordingly, using_category_.json or _category_.yml. Learn more →
• Utilize frontmatter options for configuration and customization. See the API here →
• Set a specific page as the main page [link] (if you do not intend to create a dedicated homepage. Otherwise, to create a homepage learn more here)
• Configure header navigation items in the docusaurus.config.js file. Learn more →
• Create multiple sidebars by updating sidebars.js according to your docs folder structure. Learn more →

Example of a tree structure in the docs folder:

docs
├── getting-started
│   ├── introduction.md
│   └── installation.md
└── guides
    ├── configuration.md
    └── customization.md

Using the autogenerated sidebar:

module.exports = {
  sidebars: {
    gettingStarted: [
      {
        type: 'autogenerated',
        dirName: 'getting-started',
      },
    ],
    guides: [
      {
        type: 'autogenerated',
        dirName: 'guides',
      },
    ],
  },
};

This will generate separate sidebars for the getting-started and guides folders. Adjust the header navigation items in docusaurus.config.js accordingly.

Ensure you update both the sidebars.js file and the header navigation items in docusaurus.config.js when changing the documentation structure, providing a seamless navigation experience for users.

Customization

Basic customization

• Change fonts following instructions at tailwind.config.ts
• Modify typography settings at tailwind.config.ts
• Update colors at tailwind.config.ts

Advanced customization

• Apply component-specific styles at specific module.css files
• Use mdx and React. Learn more →
• Swizzle built-in components or update our modifications at src/theme/* files. Learn more about Swizzling →
• Develop custom React pages at src/pages. Learn more →

Best practices

• When swizzling components, add comments to indicate where changes occurred
• Follow Docusaurus-specific best practices for versioning and customization. Learn more →

Deployment

Build

$ pnpm build

This command generates static content into the build directory and can be served using any static contents hosting service.

Documentation deployment guidelines

{Insert docs deployment guidelines here; i.e.: how to deploy with vercel}

e.g.:

To deploy your documentation with Vercel, follow these steps:

1. Sign up for a Vercel account if you don't have one.
2. Install the Vercel CLI by running npm i -g vercel.
3. Run vercel login in your terminal and log in using your Vercel account.
4. In your project directory, run vercel to initiate the deployment process. Follow the prompts to link your project to Vercel.
5. Once your project is linked, Vercel will deploy your documentation. After the deployment, you'll receive a URL to access your live documentation.

For subsequent deployments, run vercel --prod in your project directory to deploy your documentation to the production environment.

For more information on Vercel deployments, consult the official Vercel documentation.

Contributing to this documentation

We welcome contributions to improve and expand the documentation for {project-name}. Here's how you can contribute:

1. Report issues: If you find any errors, inconsistencies, or areas that need improvement, please open an issue on the GitHub repository. Provide a clear description of the issue and suggest a possible solution or improvement.
2. Suggest enhancements: If you have ideas for new sections, topics, or content that would be helpful to others, please share your suggestions by opening an issue on the GitHub repository.
3. Submit a pull request: If you'd like to contribute directly by fixing an issue or adding new content, please fork the repository, make changes, and submit a pull request. Ensure your changes follow the documentation guidelines and best practices outlined in the README.

Note: If you want to contribute to the {project-name} source code, please visit the repository and follow the contribution guidelines.