Welcome to the Documentation! This guide aims to facilitate contributors (like you) in understanding the readability of our knowledge base and reducing the difficulty of contributing to the repository. Our documentation demonstrates our commitment to clarity and efficiency, carefully constructed to ensure readability and coherence.
The main directories of our repository are located within the data
folder in two directories: docs
and blogs
. The blogs directory is our studio's announcements and a space for insightful blog writers (not influenced by external contributions).
We currently do not have plans to open the blog section for external contributions. Therefore, for now, you'll only see content from iNKORE! in the blog.
Here is the hierarchical structure of the documentation directory and the naming conventions for documents.
These are broad categories for grouping our content, generally named with two digits followed by a period and space, then the category name in kebab case. For example, 01. ui-elements
represents the first category in the sidebar, related to user interface elements.
-
Category Metadata Files: In each category folder, the metadata files provide basic information about our structure, offering fundamental details for categorizing content. Language-specific metadata (such as display name and description) reside in language-coded files (like
_category_.en-US.json
).For more about _category_.json, see: autogenerated#category-item-metadata
Each article has its designated folder, represented by a two-digit number followed by a period (for manual sorting if needed), a # symbol with a space, and then the article slug in kebab case. For example, an article about button design would be nested in a folder like this: 02.# button-design
. When listing controls and APIs, we prefer automatic alphabetical sorting, so you can simply write: # button-design
.
-
Article Metadata and Content Files: In these folders,
index.meta.yml
contains metadata shared across languages in YAML format. Each language-specific front matter data is contained in files namedindex.{language_code}.mdx
.For more about Font matter, see: markdown-features#front-matter and plugin-content-docs#markdown-front-matter.
Examples: index.en-US.mdx
, index.zh-CN.mdx
-
Image Naming: Images in articles should be located in the same directory as index.{language_code}.mdx and named in short kebab case, such as
create-a-new-project.png
. The choice between PNG and JPEG formats hinges on the nature of the image – with PNG preferred for crisp, detailed images, screenshots; and JPEG suited for larger, less detailed visuals.Examples:
create-new-project.png
,mountain-view.jpg
For contributors, understanding the complexity of our structure is crucial.
The powerful features of MDX allow content to integrate with its unique features. Use Markdown to clearly articulate your ideas, emphasizing important elements with Markdown formatting to guide readers to understand the information more coherently.
We encourage the use of admonitions (a feature provided by Docusaurus) in appropriate places to provide a clear and comfortable appearance. You can refer to admonitions for more information.
Remember, use the correct heading structure for steps and other scenarios. For example, this doesn't look good:
1. Download and Install
1.1 Install iNKORE Hub
You can quickly and conveniently install our product using iNKORE Hub. If you haven't...
After installing iNKORE Hub, you should have a shortcut in your Start menu that looks like this.
1.2 Open iNKORE Hub and Download MCSkinn
Click "iNKORE Hub" in the Programs section of your Start menu. Once initialized, click "Products" on the left panel.
If any error messages pop up, you should check your settings.
2. Start Using MCSkinn
2.1 Preparations
Before using MCSkinn, you need a directory representing your skin library. It can be...
Instead, write like this to generate the correct directory structure:
## Step 1: Download and Install
### Install iNKORE Hub
You can quickly and conveniently install our product using iNKORE Hub. If you haven't installed iNKORE Hub on your computer yet, click the button below.
### Open iNKORE Hub and Download MCSkinn
Click "iNKORE Hub" in the Programs section of your Start menu. Once initialized, click "Products" on the left panel.
If any error messages pop up, you should check your settings.
## Step 2: Start Using MCSkinn
### Preparations
Before using MCSkinn, you need a directory representing your skin library. It can be...
Oversized resource files will not only greatly waste our bandwidth, but also make users feel uncomfortable when loading pages. Therefore, please compress your resource files as much as possible to reduce the file size. For images, we require that a single image is not allowed to exceed 1MB (recommended not to exceed 512 KB). If your image exceeds this size, please consider using a format with a higher compression ratio, such as WebP or JPEG2000.
While using lossy compression, we ask you to keep the original file before compression in the original folder so that we can view and modify it when needed. You can create a new folder named .unused
in the article directory and put the original file in it, so that the original file will not be packaged into the site. For example, after the launcher-home image is processed, the folder structure is as follows:
launcher-home/
├── .unused/
│ ├── launcher-home.png
├── launcher-home.jpg
├── index.en-US.mdx
├── ...
For some language-specified documents (e.g. Chinese), it's essential to use spaces between [Chinese] and [English/letters/numbers/minor-symbols].
All punctuation marks should be half-width except for commas, periods, question marks, and colons. All brackets should also be half-width, with a space on each side outside the brackets. (Slashes may not have spaces around them).
For short date, please use MM/dd/yyyy
format (e.g 05/02/2024
). for long date, it should be like September 20th, 2023
.
For time, always follow HH:mm
or HH:mm:ss
rule (e.g. 16:20
, 08:06:45
). The military time (24-hour clock) will always be used.
The rules above applies to all documents and all locales, no matter what language the document is.
For example, avoid writing like this:
2024.5.2 4:08 | 2nd May 2024 | 2024年5月2日下午4点8分
我买了34个苹果(是红的)和1只鸡【不知道是公鸡 / 还是 / 母鸡】。
Instead, write like this for better readability:
05/02/2024 16:08 | May 2nd, 2024 | 5 月 2 日 2024 年,16:08
我买了 34 个苹果 (是红的) 和 1 只鸡 [不知道是公鸡/还是/母鸡]。
This guide aims to provide a clear and comprehensive overview of the document structure for (potential) contributors like you. It covers naming conventions, file structure, and specific rules for writing documents.
If you have any questions, you can submit an issue on Github, join our community, or contact us directly via email. If there's anything unclear in this article, feel free to tell us or submit a Pull Request. We greatly appreciate your valuable work, which makes the documentation center better!
Yep, this document was written with the help of AI,and translated by AI again.
Feel free to make translation jokes (try to keep the original meaning, don't go too far though).