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.
Why have we changed platforms from ReadMe to our custom built Developer Portal?
- 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 in 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: stores the markdown files of all our docs. They are categorized into:
- guides: 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
excerptfield 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 dev-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 your content to be published, you should 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, which should match the slug.
- slug: slug to the article's link, which 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 notes, 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 notes, readable when the user clicks on the
- hidden: boolean that makes the article not discoverable by search engines and our internal search if
true. Know more in How can I hide articles from search engines. - createdAt: creation date (UTC) and time in this format
{YYYY}-{MM}-{DD}T{HH}:{MM}:{SS}.{mmm}Z. - updatedAt: update date (UTC) in this format
{YYYY}-{MM}-{DD}T{HH}:{MM}:{SS}.{mmm}Z. - seeAlso: adds articles in the
See alsosection, 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" - hidePaginationPrevious: boolean that hides in the article's footer a hyperlink to the previous article listed on the navigation. Mark as
trueto hide the link to the previous doc on the navigation. - hidePaginationNext: boolean that hides in the article's footer a hyperlink to the next article listed on the navigation. Mark as
trueto hide the link to the following doc on the navigation.
- 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, see How to add images to articles.
- Ask team leaders to run the portal's build.
The slugs used in our previous version of Developer Portal were mostly maintained. You shouldn't have to worry about previous slugs.
- New guide: 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.
- API Reference: the URL structure of the Developer Portal API reference has the endpoint's path as part of it. It includes
/api-reference/{category in API Reference}#{operation}-{endpoint's path}.
For the content to be rendered properly, it is mandatory that slugs are unique, so no article should have a repeated title. Learn how to fill in titles in frontmatter.
The dev-portal-content repository just stores our documentation, it is not automatically synched to be rendered in the Developer 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, you need to create a pull request in the devportal repository.
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 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": []
},
...
]
},
...To add new 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 link in the
#dev-portal-prSlack channel for approval.
After creating a file for a new API reference in openapi-schemas, follow these steps so it shows in Dev Portal's navigation:
- Open a branch in the devportal repository.
- In the
src/pages/api/openapi/[slug].tsxfile, editreferencePathsby adding the API schema file name exactly as saved in openapi-schemas and its corresponding slug on Developer Portal. Follow this syntax:'{schemaFileName}': '{slug}'. - Repeat step 2 in the
src/utils/getReferencePaths.tsfile, editingfileSlugMapwith the same information. - Add the API category and all its endpoints in
public/navigation.json, following these instructions and making sure endpoints are added in this format. - Open a PR with all the changes.
- Send the PR in
#dev-portal-prSlack channel for approval. - After approval, merge the PR.
ℹ️ If you have any questions about this process, check out this example pull request to publish the Shipping Network API.
The URL structure of the Developer Portal API reference has the endpoint's path as part of it. For example, the List shipping policies endpoint's URL is https://developers.vtex.com/docs/api-reference/logistics-api#get-/api/logistics/pvt/shipping-policies, and the endpoints path is /api/logistics/pvt/shipping-policies.
Therefore, once you change the endpoint's path, the corresponding URL in the Developer Portal will change as well, and it will be necessary to update the left navigation.
❗ Currently, it is not possible to create redirects from an endpoint URL to its updated version. If necessary, update the links in the most strategic documentations related to that endpoint, to decrease 404 errors.
To update the left navigation after changing an endpoint's path follow the steps below:
-
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 the old endpoint slug and replace it with the new slug in the
endpointfield. For example:{ "name": "Update shipping policy", "slug": "logistics-api", "type": "openapi", "method": "PUT", "origin": "", "endpoint": "/api/logistics/pvt/shipping-policies/-id-", "children": [] }⚠️ Don't change theslugfield. It should have the same value as the API category slug. -
Open a PR.
-
Send the PR in
#dev-portal-prSlack channel for approval. -
After approval, merge the PR.
We recommend using a simple markdown syntax to add callouts:
>ℹ️ Information type callout>⚠️ Warning type callout>❗ Danger type calloutThe following complex syntax is also supported:
[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]- 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.
ℹ️ This repository uses JSDELIVR as a CDN for adding images with files stored in GitHub. Thus, you can also use the image CDN URL instead of going through steps 3 to 5. To do this, format your image URL like so:
https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@{branch}/{path}/{imgFileName}. For instance, the CDN URL for this image ishttps://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/docs/guides/Getting-Started/getting-started/making-your-first-request-1.png.
Note that we have configured an action that converts images to this CDN automatically, so both methods can be used.
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 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 file netlify.toml, you will find an array of redirects. Add the one you want to create following this format, replacing
fromandtowith the desired slugs:[[redirects]] force = true from = "/vtex-rest-api/docs/:slug" status = 308 to = "/docs/guides/:slug"Make sure you add specific redirects before more global redirects, otherwise they will have no effect. For now, hashlinks (
#) are not supported in the source slug. -
Open a PR. Netlify will generate a preview link for you to test the redirect.
-
Send the PR in
#dev-portal-prSlack channel for approval. -
After approval, merge the PR.
API Reference: what about the openapi-schemas repository?
All API Reference is still documented and managed through our usual repository, openapi-schemas. Nothing's changed here. There is a 5 minute cache between merged PRs in the openapi-schemas and the Developer Portal, but it should be rendered automatically.
All docs should be included in the dev-portal-content repository. If their readme.md file 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.
- 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
We have embedded a GitHub action called check-links.yml to review all URLs mentioned in a file and check 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.
Broken links will appear in red in your code editor tool (VSCode), and you can learn more about it by clicking on Details.