From 4dcb9508cd87841299a9fc328bb0c23c6a42d676 Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Wed, 16 Jul 2025 13:38:06 +0200 Subject: [PATCH 1/2] add best practice how to format our docs md files --- README.md | 144 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 116 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index f4f218de..b92e8ca9 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,171 @@ -# Website +# 🌐 Website This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. -### Installation +--- + +## Installation ```bash pnpm install ``` -### Local Development +--- + +## Local Development -clone this repository +Clone this repository and start the local dev server: ```bash pnpm 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. +This command will launch a local development server and open the site in your browser. Changes are hot-reloaded automatically. ### Start docs in German -To see the docs in German you need to start it with the following command +To launch the documentation in German, run: ```bash pnpm run start --locale de ``` -It is not possible to switch between the languages via the language switcher +> ⚠️ Switching languages via the language switcher is currently not supported. + +--- -### Build +## Build ```bash pnpm build ``` -This command generates static content into the `build` directory and can be served using any static contents hosting service. +This command generates static content in the `build` folder. You can serve it using any static file hosting service. -### Deployment +--- + +## Deployment -Using SSH: +### Using SSH: ```bash USE_SSH=true pnpm deploy ``` -Not using SSH: +### Without SSH: ```bash GIT_USER= pnpm 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. +If you're using GitHub Pages, this will push the production build to the `gh-pages` branch. + +--- + +## Screenshot Guidelines + +| Component | Width | +|:----------------|:-----------------:| +| Full screen | 1920px | +| Menu | 400px | +| Pop-up / Modal | 500px | + +> Highlight key elements in the screenshot with red borders or boxes if needed. + +--- + +## Markdown Guidelines + +To maintain a consistent structure across all docs, follow these formatting conventions: + +### Frontmatter Example + +All `.md` files must begin with a valid frontmatter block: + +```yaml +--- +id: getting-started +title: Getting Started +sidebar_position: 1 +description: A quick intro to OpenCloud +--- +``` + +- `id` must be unique and match the filename (without `.md`) +- `sidebar_position` defines the ordering in the sidebar +- `description` is required to ensure consistent SEO metadata and link previews. Always include a meaningful and concise description. ------ +--- + +### Heading Hierarchy + +Use the correct heading levels: + +```markdown +# Page Title + +## Section Heading + +### Subsection Heading + +#### Optional Sub-subsection +``` + +> 🚫 Do not skip heading levels (e.g., don’t go from `##` directly to `####`). + +--- + +### Info Blocks -### Standard for screenshots +Use Docusaurus-style info blocks to highlight important content: -#### Defined size for screenshots +```markdown +:::tip +Helpful tip content goes here. +::: -| Component | Size | -|:-----------------| :-: | -| complete screen | width: "1920px" | -| menu | width: "400px" | -| pop up | width: "500px" | +:::info +General information goes here. +::: -The screenshot should show the important aspects and you can put red frames around the specific buttons or areas. +:::warning +Warnings go here. +::: + +:::danger +Critical notices go here. +::: +``` + +--- + +### Lists and Steps + +Use regular markdown for ordered lists. Do **not** nest deeply. + +```markdown +1. First step +2. Second step +3. Third step +``` --- -## Please format before pushing +## Format Before Pushing -Before pushing your changes to the repository, make sure the code and documentation are properly formatted. Run the following commands: +Before committing changes, ensure proper formatting using: -```shell +```bash pnpm format:write pnpm lint:md:fix ``` -These commands ensure that: +These commands will: + +- Format all project files +- Lint and auto-fix markdown formatting +- Ensure consistent style across documentation + +--- -- All files follow the project's formatting standards -- Markdown files are linted and auto-fixed for consistent structure and readability \ No newline at end of file +Thanks for helping us keep the docs clean, professional, and easy to read! \ No newline at end of file From ddabcb91a7f73e47a0e3c4e5010a7ffc8f992854 Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Wed, 16 Jul 2025 13:43:57 +0200 Subject: [PATCH 2/2] add info about img and alt text --- README.md | 38 +++++++++++++++++--------------------- 1 file changed, 17 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index b92e8ca9..57d87e4b 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,6 @@ This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. ---- ## Installation @@ -10,7 +9,6 @@ This website is built using [Docusaurus](https://docusaurus.io/), a modern stati pnpm install ``` ---- ## Local Development @@ -32,7 +30,6 @@ pnpm run start --locale de > ⚠️ Switching languages via the language switcher is currently not supported. ---- ## Build @@ -42,7 +39,6 @@ pnpm build This command generates static content in the `build` folder. You can serve it using any static file hosting service. ---- ## Deployment @@ -60,19 +56,28 @@ GIT_USER= pnpm deploy If you're using GitHub Pages, this will push the production build to the `gh-pages` branch. ---- ## Screenshot Guidelines -| Component | Width | -|:----------------|:-----------------:| -| Full screen | 1920px | -| Menu | 400px | -| Pop-up / Modal | 500px | +| Component | Width | +|:----------------|:------:| +| Full screen | 1920px | +| Menu | 400px | +| Pop-up / Modal | 500px | > Highlight key elements in the screenshot with red borders or boxes if needed. ---- +### Example + +To include a screenshot in your documentation, use the following format: + +```jsx +EXAMPLE +``` + +- Use `require(...)` for image paths so they are bundled correctly by Docusaurus +- Always include a meaningful `alt` text to improve accessibility and SEO + ## Markdown Guidelines @@ -95,8 +100,6 @@ description: A quick intro to OpenCloud - `sidebar_position` defines the ordering in the sidebar - `description` is required to ensure consistent SEO metadata and link previews. Always include a meaningful and concise description. ---- - ### Heading Hierarchy Use the correct heading levels: @@ -111,9 +114,8 @@ Use the correct heading levels: #### Optional Sub-subsection ``` -> 🚫 Do not skip heading levels (e.g., don’t go from `##` directly to `####`). +> Do not skip heading levels (e.g., don’t go from `##` directly to `####`). ---- ### Info Blocks @@ -137,8 +139,6 @@ Critical notices go here. ::: ``` ---- - ### Lists and Steps Use regular markdown for ordered lists. Do **not** nest deeply. @@ -149,8 +149,6 @@ Use regular markdown for ordered lists. Do **not** nest deeply. 3. Third step ``` ---- - ## Format Before Pushing Before committing changes, ensure proper formatting using: @@ -166,6 +164,4 @@ These commands will: - Lint and auto-fix markdown formatting - Ensure consistent style across documentation ---- - Thanks for helping us keep the docs clean, professional, and easy to read! \ No newline at end of file