This repository is the source for https://okteto.com/docs. If you'd like to contribute to the documentation, please first check out our contributing guide for info on how to get started.
You'll need to install node
20+ and yarn
1.22+ locally in order to be able to build the doc site locally.
Clone the repo and then run:
yarn
yarn start
However, it is possible to build the website locally using okteto itself without any need to install required dependencies and specific version of build tool.
You can launch a remote Development Environment with Okteto on any Kubernetes cluster with the Okteto CLI.
-
In order to configure Okteto CLI to use Okteto, run the following command at the root (replace the URL with your Okteto instance):
okteto context use https://okteto.example.com
Note: If you'd like to use any Kubernetes cluster with Okteto CLI, run the
okteto context
command and select the context you'd like to go with using arrows key -
Once the context is setup, run the
okteto up
command. This will make sure the required docker images are built by Okteto CLI. -
Once the development environment is built, go to your Okteto and preview your changes. As soon as you hit the save, the changes will be reflected in Okteto as it'd look like in production.
A new version of the docs is created once the documentation for a certain version is "finished". This is typically done in preparation of a new release.
Review the content of src/content/variables.json
and update the values of cliVersion
and chartVersion
.
If the release comes with a new or a removed Kubernetes version, update kubernetesMinVersion
and kubernetesMaxVersion
accordingly.
To create a new version, run the following commands:
yarn run docusaurus docs:version 1.XX
This will create a new version with the docs on your current branch.
The default version of the docs is created and published once a new version of Okteto is available. This is typically done as part of the release process of Okteto Self-Hosted.
Modify the presets.docs.versions
section of docusaurus.config.js
as follows:
-
Update
lastVersion
to the new official version -
Update
current
to unreleased version in development -
Update the values of the
path
of the previous official version in theversions
subsection to match the version number.Before
"1.4": { label: "1.4", path: "/", banner: "none", },
After
"1.4": { label: "1.4", path: "1.4", banner: "none", },
-
Add a new entry in the
versions
subsection to match the new official version, with/
as the path."1.5": { label: "1.5", path: "/", banner: "none", },
Modify the redirection rules on netlify.toml
so that /docs/<OFFICIAL_VERSION>/
redirects to /docs
and /docs/unreleased/
redirects to /docs/<CURRENT_VERSION>
# Redirect official version to docs root
[[redirects]]
from = "/docs/1.5/*"
to = "/docs/:splat"
status = 301
# Redirect unreleased to "current" version
[[redirects]]
from = "/docs/unreleased/*"
to = "/docs/1.6/:splat"
status = 302
Update /src/pages/archives.md
with the new latest version
okteto#314 is a good example of how to set up the files
Once the new version is live in production, you need to request a new search index to Algolia.
- Log in Algolia
- On the crawlers’ page, select "Okteto"
- Click on "Restart crawling"
It should take a few minutes and the search index will be completed.
Sometimes, documentation is specific to a product tier. You can add a badge beside headings using the TiersList component.
Tiers is a string
of tier separated by a space
# Page heading<TiersList tiers="Scale Self-Hosted" />