Welcome to the VTEX Developer Portal content repository! Here you will find the files for all guides included in that documentation portal. It is managed by the Tech Writing team at VTEX, with lots of love, sweat and PRs.
We're so glad you're here! It means you care about sharing knowledge through documentation ❤️ 📝. So come along, get comfy and learn how to contribute with documentation, manage content and fix errors in this repository.
- Faster navigation
- More control over the search
- Create an interface completely controlled by us
- Managing content in Github
- High efficiency: we saved a considerable amount of our monthly budget.
We have created a new organization in Github to host our documentation: vtexdocs.
You can find all repositories included in it /vtex/education-tools
.
They each serve a different purpose, and will be mentioned in the FAQ below, depending on which action you wish to perform.
You will find the following folders in this repository:
- .github: stores workflows configured for this repository.
- docs: where the markdown files of all our docs are stored. They are categorized into:
- guides: all API guides.
- release-notes: release notes included in our changelog.
- vtex-io: all VTEX IO guides.
- docs-utils: scripts used to import documentation from Readme.
- images: stores images imported from Readme.
- readme-api-md: stores API Reference's markdown imported from Readme/
- .gitignore: stores files that should be ignored by Github.
We're so glad you're here! Thanks for being interested.
- Open a branch in the dev-portal-content repository.
- Add a new file in the desired folder, following our template.
- Complete the frontmatter.
The
excerpt
field is mandatory for release notes. - Add your content in markdown.
- Add images in the chosen guide’s folder, if you wish.
- To determine the left navigation's order, follow these instructions.
- Submit your PR for review.
The /developer-portal-content
repository just stores our documentation, it is not automatically synched to be rendered in the Dev Portal - yet. For now, when a new content is added to it, it is just included in the desired folder. For it to appear in the Developer Portal, our Tech Writing team leaders must run the portal's build.
⚠️ Note that we have a limitation of PRs by hour, so we have to accumulate the day's PRs to be all approved and merged by our Tech Writing team leaders. This means that if you want a content to be published, submit your PR for review with at least 2 days in advance from the desired publication date!
The frontmatter is the table with metadata about the article you're adding. It contains the following fields:
- title: article's title, should match the slug.
- slug: slug to the article's link, should match the title.
- excerpt: brief description of release notes and guides, like a synopsis or TLDR.
- Release notes: it is rendered as a synopsis of the release note, that is readable when the user clicks on the
▶️ collapsible button next to the release's title, in our changelog UI. This field is mandatory for release notes! Character limit: 400. - Guides: it is rendered as the greyed-out sentence at the bottom of the title, with a brief TLDR for that article. Character limit: 120.
- Release notes: it is rendered as a synopsis of the release note, that is readable when the user clicks on the
- hidden: boolean that makes the article not discoverable by search engines and our internal search. Know more in How can I hide articles from search engines
- createdAt: creation date, automatically filled in.
- updatedAt: update date, automatically filled in.
- seeAlso: adds articles in the
See also
section, at the footer of the content. Should be filled in when there's a recommended reading sequence for the articles you are managing. It should be filled with the slug of the chosen article. ExampleseeAlso: - "/docs/guides/vtex-io-documentation-2-prerequesites"
- Make sure you have a unique slug.
- Make sure your slug is the exact copy of your title.
- Images must be saved in the repository. To add it to your markdown, mention its path in the desired place of your guide's body.
- Ask team leaders to run the portal's build.
The slugs used previously in our old Dev Portal were mostly maintained. You shouldn't have to worry about previous slugs.
For new content, an article's title will become the page's slug always. Do not create a slug that is different than the title, the portal will not interpret it otherwise.
For the content to be rendered properly, it is mandatory that slugs are unique, so no article should have a repeated title.
In the articles file, we included the header below. Add in the slug column the exact title, between dashes.
The /developer-portal-content
repository just stores our documentation, it is not automatically synched to be rendered in the Dev Portal - yet. For now, when a new content is added to it, it is just included in the desired folder. For it to appear in the Developer Portal in the order that you choose for the left navigation, other PRs must be made.
The portal's navigation comes from the navigation file. It is a json object listing the navigation and hierarchy of all contents in Developer Portal.
The excerpt below represents the first articles of the API Guides section, for instance.
{
"documentation": "API Guides",
"slugPrefix": "docs/guides/",
"categories": [
{
"name": "Getting Started",
"slug": "getting-started-category",
"origin": "",
"type": "category",
"children": [
{
"name": "Introduction",
"slug": "getting-started",
"origin": "",
"type": "markdown",
"children": [
{
"name": "Platform overview",
"slug": "getting-started-platform-overview",
"origin": "",
"type": "markdown",
"children": []
},
{
"name": "List of REST APIs",
"slug": "getting-started-list-of-rest-apis",
"origin": "",
"type": "markdown",
"children": []
},
{
"name": "Authentication",
"slug": "getting-started-authentication",
"origin": "",
"type": "markdown",
"children": []
},
{
"name": "Making your first request",
"slug": "getting-started-making-your-first-request",
"origin": "",
"type": "markdown",
"children": []
}
]
},
{
"name": "Catalog",
"slug": "catalog-overview",
"origin": "",
"type": "markdown",
"children": []
},
{
"name": "Orders",
"slug": "orders-overview",
"origin": "",
"type": "markdown",
"children": []
},
{
"name": "Checkout",
"slug": "checkout-overview",
"origin": "",
"type": "markdown",
"children": []
},
{
"name": "Payments",
"slug": "payments-overview",
"origin": "",
"type": "markdown",
"children": []
},
{
"name": "Search",
"slug": "search-overview",
"origin": "",
"type": "markdown",
"children": []
},
{
"name": "Promotions",
"slug": "promotions-overview",
"origin": "",
"type": "markdown",
"children": []
},
{
"name": "Pricing",
"slug": "pricing-overview",
"origin": "",
"type": "markdown",
"children": []
},
{
"name": "Account management",
"slug": "account-management",
"origin": "",
"type": "markdown",
"children": [
{
"name": "Checking which user is currently authenticated",
"slug": "checking-which-user-is-currently-authenticated",
"origin": "",
"type": "markdown",
"children": []
}
]
}
]
},
To add the created content in the left navigation:
-
Open a branch in the /devportal repository.
⚠️ Before you start adding commits, read the repository's readme file! Commits must be done in a certain format for your PR to be approved. -
In the navigation.json file, locate where you want the new content to appear. (Yes, it is a long document, be patient!)
-
Copy the structure below, and replace the values for your desired content.
{
"name": "Checking which user is currently authenticated",
"slug": "checking-which-user-is-currently-authenticated",
"origin": "",
"type": "markdown",
"children": []
}
- Paste the object in the desired spot.
- Open a PR.
By opening a PR, a bot will present a preview for you to test the navigation. With each commit, the preview will be updated.
- Test your navigation through the preview.
- Send the PR in #dev-portal-pr channel for approval.
You can use the following syntax for adding callouts, but prefer the simpler markdown version:
[block:callout]
{
"type": "info",
"body": "Check the new [Payments onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.",
"title": "Onboarding guide"
}
[/block]
[block:callout]
{
"type": "warning",
"body": "Check the new [Payments onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.",
"title": "Onboarding guide"
}
[/block]
[block:callout]
{
"type": "danger",
"body": "Check the new [Payments onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.",
"title": "Onboarding guide"
}
[/block]
>ℹ️ Information type callout
>⚠️ Warning type callout
>❗ Danger type callout
- Access the dev-portal-content/docs/guides folder.
- Upload the images you wish to include in your guide in the same folder your article is located.
- Access the file in Github web.
- Open the raw version of the uploaded file by opening the image in a new tab.
- Save the URL.
- Mention the URL in your markdown.
When you publish an article in Developer Portal and wish that only those with the link can access it, you can hide it from search engines. This is useful for products in Beta that need documentation for specific clients, instead of publicly available docs, for example.
To do so, when creating the article fill in the header with the value hidden: true
. You can keep the article out of the navigation bar by not making any changes in navigation.json
.
---
title: "Orders v2"
slug: "orders-getting-started"
hidden: true
createdAt: "2022-09-27T20:34:46.354Z"
updatedAt: "2022-10-04T14:36:08.692Z"
---
️ Be aware that this will hide your article not only in Developer Portal searches, but also in other sites, like Google.
Open a PR in this repository.
Netlify will generate a preview link for you to test the redirect.
Follow this format in your PR:
{
source: '/vtex-rest-api/docs/:slug',
destination: '/docs/guides/:slug',
permanent: true,
},
All API Reference is still documented and managed through our usual repository. Nothing's changed here. There is a 5 minute cache between PRs in the /openapi-schemas
repository and the Dev Portal, but it should be rendered automatically.
All docs should be included in the /dev-portal-content repository. If the readme is not yet included, create a new file, and copy and paste the text.
How to fix the error type Error: There are incorrectly formatted code blocks in this file
in #dev-portal-logs?
This error means that there is a `
loose somewhere in the document. The system reads it as an inline code block.
This error should already be fixed. Check the log's age to see if it is still valid.
What causes 404 errors?
- Broken callouts
- Broken images
- Missing closing tags in HTML
- Links mentioned in other articles containing previous Dev Portal slugs, or mentions to headings
- Redirects not made from older URLs
- Content does not exist in /dev-portal-content, only on Readme
404 automatic checker in files We have embedded a Github action called check-links.yml to review all URLs mentioned in a file, and checking if they return 404 errors. If there's a link experiencing the 404 error in your file, you must fix it so the branch can be merged.
To identify the broken link:
The broken link will appear in red in your code editor tool (VSCode), and you can learn more about it by clicking on Details
.