Fix: Documentation rendering issues

docs/en/changelog/changelog-test.md

@@ -0,0 +1,17 @@
+---
+title: 'Changelog test file'
+id: changelog-test-file
+status: PUBLISHED
+createdAt: 2024-11-05T19:24:22.388Z
+updatedAt: 2024-11-05T19:24:22.388Z
+publishedAt: 2024-11-05T19:24:22.388Z
+firstPublishedAt: 2024-11-05T19:24:22.388Z
+contentType: trackArticle
+productTeam: Localization
+slugEN: changelog-test-file
+locale: en
+trackId: 5PxyAgZrtiYlaYZBTlhJ2A
+trackSlugEN: changelog-test-file
+---
+
+This is a test file to check the connection between the documentation repository and the webpage repository.

docs/en/documentation/app-documentation.md

@@ -0,0 +1,123 @@
+---
+title: 'App documentation'
+id: edu0006
+status: PUBLISHED
+createdAt: 2024-12-04T19:24:22.388Z
+updatedAt: 2024-12-04T19:24:22.388Z
+publishedAt: 2024-12-04T19:24:22.388Z
+firstPublishedAt: 2024-12-04T19:24:22.388Z
+contentType: trackArticle
+productTeam: Education
+slugEN: app-documentation
+locale: en
+trackId: 5PxyAgZrtiYlaYZBTlhJ2A
+trackSlugEN: app-documentation
+---
+
+An App documentation guide helps users understand the [VTEX app](https://developers.vtex.com/docs/guides/vtex-io-documentation-what-is-a-vtex-app), the installation, and the configuration processes.
+
+ℹ️ To add documentation in an app, you must use the [Docs builder](https://developers.vtex.com/docs/guides/vtex-io-documentation-docs-builder). The documentation is written in Markdown files, inside the app’s repository. By using the Docs builder, the documentation becomes publicly available at the [VTEX Developer Portal](https://developers.vtex.com/).
+
+In this guide, you will learn about the available template, general guidelines, and see examples of Onboarding articles. 
+
+> ⚠️ This guide is part of the [App Store guidelines](https://developers.vtex.com/docs/guides/vtex-io-documentation-homologation-requirements-for-vtex-app-store) and one of the requirements to submit an app to the homologation process and [make it available in the App Store](https://developers.vtex.com/docs/guides/vtex-io-documentation-homologation-requirements-for-vtex-app-store).
+
+<details>
+<summary><b>App documentation template</b></summary>
+
+```md
+# {Insert the app's name}
+
+The `{insert app's name}` is responsible for `{app's purpose}` so you can `{job to be done}`.
+
+![insert-an-image-preview](/)
+
+## Before you begin
+
+You need to have `{insert what the user needs to have: an account in another platform, CLI, knowledge in another app, etc}`.
+
+If you do not have `{insert what the user needs to have and how to obtain it}`.
+
+## Installation
+
+1. [Install](https://developers.vtex.com/vtex-developer-docs/docs/vtex-io-documentation-installing-an-app) the `{insert app's name}` app in the desired VTEX account by running `vtex install {appVendor}.{appName}` in your terminal.
+2. (Optional, for frontend apps) Open your store’s Store Theme app directory in your code editor.
+3. (Optional, for frontend apps) Open your app's `manifest.json file` and add the `{insert app's name}` app under the `peerDependencies` field.
+
+
+      "peerDependencies": {
+          "vtex.{appName}": "{appVersion}"
+      }
+
+
+4. (Optional, for frontend apps) Declare the `{insert app's name}` app in the desired template. For example:
+
+      "store.home": {
+          "blocks": [
+      +     "{app-name}",
+          ]
+      },
+
+*![insert-an-image-preview](/)*
+
+## Configuration
+
+Once you have installed the app, you can `{describe the app's configuration in the VTEX Admin as defined in the settingsSchema[https://developers.vtex.com/docs/guides/vtex-io-documentation-manifest#settingsschema], for example}`.
+
+1. `First step`.
+2. `Second step`.
+3. `Third step`.
+
+## Customization (optional, for frontend apps)
+
+To apply CSS customizations to this and other blocks, follow the instructions given in the recipe on [Using CSS Handles for store customization](https://developers.vtex.com/vtex-developer-docs/docs/vtex-io-documentation-using-css-handles-for-store-customization).
+
+| CSS Handles |
+| ------------------ |
+| csshandlesName |
+| csshandlesName |
+| csshandlesName |
+
+## How the app works (Optional)
+
+When the app requires user interaction beyond the Admin configuration. This section is recommended for [Admin apps](https://learn.vtex.com/docs/course-admin-lang-en).
+
+`{Detail what can be done with the app and show the steps to perform each operation.}`
+
+## Contributors
+
+Thanks go to these wonderful people:
+
+- `{insert the GitHub username}`
+
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind are welcome.
+```
+</details>
+
+## General guidelines
+
+| **Topic** | **Description** | ✅ Do | ❌ Don’t |
+| :---- | :---- | :---- | :---- |
+| **Target audience** | Identify your readers. | Differentiate between developers and business users. | Assume a single audience. |
+| **Learning objectives** | Define the user's takeaway. | Clearly state what users should learn. | Leave learning goals ambiguous. |
+| **Title** | A clear and concise title. | Use the app name and a verb describing the learning objective. Capitalize the first letter of each word. | Include punctuation, version numbers, or the word "App". |
+| **Introduction** | Briefly introduce the app and its benefits. | Summarize the app's purpose and user benefits. Include an image and callouts for important notes. | Focus solely on technical details.  |
+| **Before you begin (Optional)** | List requirements before installation. | Use clear bullet points or checklists. Utilize callouts if applicable. | Write lengthy paragraphs explaining prerequisites. |
+| **Installation** | Provide a step-by-step guide with code snippets (if applicable) | Offer clear and concise steps. Enhance clarity with code snippets. | Skip steps or lack specific instructions. |
+| **Configuration** | Guide users through configuring the app. | List all essential settings with detailed steps as defined in the [settingsSchema](https://developers.vtex.com/docs/guides/vtex-io-documentation-manifest#settingsschema). | Omit configuration details. |
+| **How it works** | (Optional) Detail the app functions and provideoffer steps for usingutilizing the app. | Use numbered lists for each operation, with clear and concise steps. Use images to illustrate the UI. | Skip steps or lack specific instructions. |
+| **Customization** | (Optional) ProvideOffer steps for customizing the app. | Include [CSS handles](https://developers.vtex.com/vtex-developer-docs/docs/vtex-io-documentation-using-css-handles-for-store-customization) and a related table if applicable. Reference external documentation for CSS customization. |  Ignore customization options. |
+| **Contributors** | (Optional) Acknowledge contributors. | Follow the [All-Contributors specification](https://github.com/all-contributors/all-contributors). | Omit recognition of contributors. |
+| **Callouts** | Highlight information using callouts. | Use the provided callout types (Information, Warning, Danger) with appropriate messages.:  | Use generic text to highlight information. |
+
+## Examples of App documentation articles
+
+* [Breadcrumb](https://developers.vtex.com/docs/apps/vtex.breadcrumb)  
+* [SKU Selector](https://developers.vtex.com/docs/apps/vtex.store-components/skuselector)  
+* [Store Locator](https://developers.vtex.com/docs/apps/vtex.store-locator)  
+* [Store Sitemap](https://developers.vtex.com/docs/apps/vtex.store-sitemap)  
+* [Assembly Options](https://developers.vtex.com/docs/guides/assembly-options-app)  
+* [Installing Google Tag Manager](https://developers.vtex.com/docs/guides/vtex-io-documentation-installing-google-tag-manager)  
+* [Live Shopping](https://developers.vtex.com/docs/apps/vtexventures.livestreaming)  
+* [Personal Shopper](https://developers.vtex.com/docs/apps/vtexventures.personal-shopper-free)  
+* [Pinterest app](https://developers.vtex.com/docs/apps/pinterestpartnerbr.pinterest@1.x)

docs/en/documentation/best-practices-for-writing-documentation.md

@@ -0,0 +1,96 @@
+---
+title: "Best practices for writing documentation"
+id: edu0001
+status: PUBLISHED
+createdAt: 2024-12-03T19:24:22.388Z
+updatedAt: 2025-01-27T12:00:00.388Z
+publishedAt: 2024-12-03T19:24:22.388Z
+firstPublishedAt: 2024-12-03T19:24:22.388Z
+contentType: trackArticle
+productTeam: Education
+slugEN: best-practices-for-writing-documentation
+locale: en
+trackId: 5PxyAgZrtiYlaYZBTlhJ2A
+trackSlugEN: best-practices-for-writing-documentation
+---
+
+At VTEX, our goal for documentation is to make everything as simple and clear as possible for users working with or interested in VTEX solutions.
+
+We welcome contributions to VTEX documentation and encourage you to help improve the user experience. There are several ways to contribute, depending on the documentation portal you're interested in and your preferred method. Check our [Contribution Guidelines](https://language-hub.netlify.app/docs/documentation/contribution-guidelines) for more information.
+
+Before contributing to the documentation, make sure to:
+
+-
+
+## Define the documentation structure
+
+Before you start writing, it’s important to understand your target audience and the specific goals of your documentation. To help you define the documentation objectives, answer the following questions:
+
+- What do you want users to achieve after reading your documentation?
+- What are the essential tasks or concepts they need to understand?
+- What additional information could enhance user understanding?
+
+### Identify the audience
+
+To help you define the audience, answer the following questions:
+
+- Who is the target audience for that information?
+- What are they trying to do?
+
+At VTEX, we have the following audience as our documentation readers:
+
+| Audience type | Description   |
+| :------------ | :------------ |
+| **Beginner**  | New to ecommerce operations and VTEX, with little to no prior experience. Their main challenge is adapting to the platform and the ecommerce context. |
+| **Operational**      | Handles daily ecommerce tasks, such as SKU registration and promotion management. Familiar with the ecommerce context but may encounter problems that they can’t solve by themselves. |
+| **Highly Technical** | Builds or integrates technical solutions with VTEX. They work on store implementations, app development with our solutions, and integrations with partner systems via VTEX APIs. This audience requires in-depth technical documentation that describes the characteristics of all our features and indicates how to address business needs. |
+
+### Checklist to define the documentation objectives
+
+To help you define the documentation context, see the checklist below:
+
+#### Audience
+
+  <input type="checkbox" id="beginner" name="audience" value="Beginner">
+  <label for="beginner">Beginner</label><br>
+  <input type="checkbox" id="operational" name="audience" value="Operational">
+  <label for="operational">Operational</label><br>
+  <input type="checkbox" id="developer" name="audience" value="Developer">
+  <label for="developer">Highly Technical</label><br><br>
+
+#### Learning Category
+
+  <input type="checkbox" id="awareness" name="learning_category" value="Awareness">
+  <label for="awareness">Awareness - The audience can describe or paraphrase a concept or feature.</label><br>
+  <input type="checkbox" id="comprehension" name="learning_category" value="Comprehension">
+  <label for="comprehension">Comprehension - The audience can understand a concept to support decision-making.</label><br>
+  <input type="checkbox" id="applicable_skill" name="learning_category" value="Applicable Skill">
+  <label for="applicable_skill">Applicable Skill - The audience can follow instructions to complete a task.</label><br><br>
+
+#### Learning Objective
+
+  <input type="checkbox" id="tasks" name="learning_objective" value="tasks">
+  <label for="tasks">Choose one or two tasks or concepts that the content will discuss.</label><br>
+  What should someone be able to do or understand after reading this article? Choose one or two tasks or concepts that the content will discuss.
+  Template example:
+
+  ```md
+  "Create a guide on {add the guide’s purpose}. The guide should emphasize clarity, structure, and user-friendliness. It's intended for {add the guide’s audience}."
+  ```
+
+## Documentation style guide
+
+This guideline is the VTEX interpretation of stylistics as a discipline and explains particular language choices when creating functional and technical content about our platform.
+
+### Style guide principles
+
+| Principle  | Orientation  | Usage  |
+| :--------- | :----------- | :----- |
+| **Clarity and conciseness** | <ol><li>Use simple language and avoid jargon. Break down complex concepts into smaller, easier-to-understand steps.</li><li>Use clear and informative headings and subheadings to guide readers through the documentation.</li></ol>| <ol><li>Instead of *Utilize the API endpoint for product creation.* write, *Create a new product using the API.*</li><li>Use headings like *Getting started*, *Instructions*, and *Advanced features*.</li></ol>   |
+| **Consistency**             | Maintain consistency in terminology, style, and formatting throughout the documentation. | Use the same terminology for similar concepts referring to the same subject/reader consistently from the beginning to the end of the text (example: *customer* instead of *client*, and stick to *you* instead of alternating with *user* or *member*).  |
+| **Completeness**            | Make sure the documentation is both comprehensive and concise, covering all relevant topics with enough detail. | If you’re documenting a feature, include information on how to use it, common use cases, and potential troubleshooting steps. |
+| **Usability**               | Consider the user's perspective and write the documentation in a way that is easy to navigate and use. | Use clear headings, subheadings, and bullet points to organize the content. |
+| **Logical flow**            | Organize the content in a logical sequence that is easy to follow. | Start with an introduction, followed by detailed sections on specific topics. |
+| **Media and code examples** | Use media such as diagrams, screenshots, and code examples to enhance understanding. | Use screenshots, diagrams, and code snippets to illustrate examples and ensure accuracy. *Tip:* Diagrams, like platform or product architecture diagrams, can help illustrate complex processes or relationships. |
+
+For more details about these principles, see the [style guide section](LINK).