https://github.com/yougotwill/docs-starter
Documentation Website Template
https://github.com/yougotwill/docs-starter
documentation docusaurus markdown react static-site-generator template website
Last synced: about 2 months ago
JSON representation
Documentation Website Template
- Host: GitHub
- URL: https://github.com/yougotwill/docs-starter
- Owner: yougotwill
- Created: 2022-02-18T04:21:22.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2022-02-18T04:21:26.000Z (over 4 years ago)
- Last Synced: 2024-12-31T20:28:31.606Z (over 1 year ago)
- Topics: documentation, docusaurus, markdown, react, static-site-generator, template, website
- Language: JavaScript
- Homepage:
- Size: 227 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Documentation Website Template
This documentation website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
## Installation
```
$ yarn
```
## Local Development
```
$ yarn start
```
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
### Build
```
$ yarn build
```
This command generates static content into the `build` directory and can be served using any static contents hosting service.
### Serve
```
$ yarn serve
```
This command serves the static content of the `build` directory locally and opens up a browser window.
## Deployment
Using SSH:
```
$ USE_SSH=true yarn deploy
```
Not using SSH:
```
$ GIT_USER= yarn deploy
```
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
## Getting Started
### Project Structure
- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](https://docusaurus.io/docs/docs-markdown-features)
- `/src/` - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files in here but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting`/processing
- `/src/pages` - Any files within this directory will be converted into a website page. More details can be found in the [pages guide](https://docusaurus.io/docs/creating-pages)
- `/static/` - Static directory. Any contents inside here will be copied into the root of the final build directory
- `/docusaurus.config.js` - A config file containing the site configuration.
- `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar
### Metadata and Styles
1. Add your site metadata to [docusaurus.config.js](/docusaurus.config.js).
2. Pick a color and then generate the required shades using this [tool](https://docusaurus.io/docs/styling-layout#primary_color).
3. Overwrite the color variables in [custom.css](/src/css/custom.css).
4. Adjust the searchbar to match your color palette by overwriting `--aa-selected-color-rgb` with the `rgb` format of `--ifm-color-primary` in [custom.css](/src/css/custom.css) for both the light and dark themes.
### Writing docs
1. Routing works by generating url slugs using the relative path of a file / folder within the [docs](/docs) folder.
2. To order folders or files you can put `XX-` infront of the name. e.g. `01-tutorial-basics/` or `01-create-a-page.md`.
The page title can then be changed using the following methods.
1. For markdown files you can use either a `#Heading` or specify the title using the `label` field in the `YAML` frontmatter of the file.
```yaml
---
label: Tutorial Basics
---
```
2. For folders you can create a `JSON` file within the folder called `_category_.json`.
```json
{
"label": "Tutorial Basics"
}
```
#### Markdown Frontmatter
| Name | Type | Default | Description |
| ------------------------ | --------------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| `id` | `string` | file path (including folders, without the extension) | A unique document id. |
| `title` | `string` | Markdown title or `id` | The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title. |
| `pagination_label` | `string` | `sidebar_label` or `title` | The text used in the document next/previous buttons for this document. |
| `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
| `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadatas](https://docusaurus.io/docs/sidebar#autogenerated-sidebar-metadatas). |
| `sidebar_class_name` | `string` | `undefined` | Gives the corresponding sidebar label a special class name when using autogenerated sidebars. |
| `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the frontmatter, and have no effect on a Markdown title at the top of your document. |
| `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |
| `toc_min_heading_level` | `number` | `2` | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. |
| `toc_max_heading_level` | `number` | `3` | The max heading level shown in the table of contents. Must be between 2 and 6. |
| `pagination_next` | `string | null` | Next doc in the sidebar | The ID of the documentation you want the "Next" pagination to link to. Use `null` to disable showing "Next" for this page. |
| `pagination_prev` | `string | null` | Previous doc in the sidebar | The ID of the documentation you want the "Previous" pagination to link to. Use `null` to disable showing "Previous" for this page. |
| `parse_number_prefixes` | `boolean` | `numberPrefixParser` plugin option | Whether number prefix parsing is disabled on this doc. See also [Using number prefixes](https://docusaurus.io/docs/sidebar#using-number-prefixes). |
| `custom_edit_url` | `string` | Computed using the `editUrl` plugin option | The URL for editing this document. |
| `keywords` | `string[]` | `undefined` | Keywords meta tag for the document page, for search engines. |
| `description` | `string` | The first line of Markdown content | The description of your document, which will become the `` and `` in ``, used by search engines. |
| `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. |
| `slug` | `string` | File path | Allows to customize the document url (`//`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. |
| `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your docs. |
## References
[Docusaurus.io](https://docusaurus.io/)