Weaviate uses Docusaurus 2 to build our documentation. Docusaurus is a static website generator that runs under Node.js. We use a Node.js project management tool called yarn to install Docusaurus and to manage project dependencies.

If you do not have Node.js and yarn installed on your system, install them first.

Use the nvm package manager to install Node.js. The nvm project page provides an installation script.

After you install nvm, use nvm to install Node.js.

nvm install

By default, nvm installs the most recent version of Node.js. Also install the version of Node.js that is specified in .github/workflows/pull_requests.yaml. At the time of writing it is version 20.

nvm install 20
nvm use 20

Node.js includes the npm package manager. Use npm to install yarn.

npm install --global yarn

To contribute to this web site, first fork this repository and create a local copy to work on.

1. Log into your GitHub account.

2. Fork the upstream repository, https://github.com/weaviate/weaviate-io.

3. Clone the repository to your local system.

   git clone [email protected]:YOUR-GITHUB-HANDLE/weaviate-io.git
   

   For details on cloning a repository, including setting up an SSH key, see the GitHub documentation.

4. Set the remote tracking branch.

   git remote add upstream https://github.com/weaviate/weaviate-io.git
   

5. Check the remotes.

   git remote -v
   
   # The output resembles:
   
   origin	https://github.com/YOUR-GITHUB-HANDLE/weaviate-io.git (fetch)
   origin	https://github.com/YOUR-GITHUB-HANDLE/weaviate-io.git (push)
   upstream	https://github.com/weaviate/weaviate-io.git (fetch)
   upstream	https://github.com/weaviate/weaviate-io.git (push)
   

6. Configure a tracking branch.

   This step lets you track upstream changes while you work on your update. When you are ready to contribute your changes, create a pull request against the upstream/main branch.

   Get the upstream branches.

   git fetch upstream
   

   Add upstream/main as a tracking branch when you create a new project branch. You can use git checkout to set the tracking branch, or choose an alternative method that fits your workflow.

   git checkout -b your-update-branch-name upstream/main
   

Once you have a local copy of the repository, you need to install Docusaurus and the other project dependencies.

Switch to the project directory, then use yarn to update the dependencies.

cd weaviate-io
yarn install

You may see some warnings during the installation.

When the installation completes, start the yarn server to test your build.

yarn start

This will build the site and start a local server, then open http://localhost:3000/ showing the local build. If you close the terminal, the server will stop. Or press Ctrl C/Cmd C to stop the server.

This command generates static content into the build directory. You can use a hosting service to serve the static content.

yarn build

The build command is useful when you are finished editing. If you ran yarn start to start a local web server, you do not need to use yarn build to see you changes while you are editing.

The build command runs a link checker. If you are having trouble with temporarily broken links, you can update the URL_IGNORES variable to disable checking for that link.

To disable link checking, add the broken URL to the URL_IGNORES lists in these scripts:

• verify-links.sh
• verify-links-build-dev.sh

Check the link again before you submit a merge request. If the link works, remove it from the URL_IGNORES list. If the link doesn't work, tell us about it in the pull request.

Using SSH:

USE_SSH=true yarn deploy

Not using SSH:

GIT_USER=<Your GitHub username> yarn 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.

Code examples in the documentation are in one of two formats:

In many files, you will see a format similar to:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import FilteredTextBlock from '@site/src/components/Documentation/FilteredTextBlock';
import PyCode from '!!raw-loader!/_includes/code/howto/manage-data.create.py';
import TSCode from '!!raw-loader!/_includes/code/howto/manage-data.create.ts';

<Tabs groupId="languages">
  <TabItem value="py" label="Python">
    <FilteredTextBlock
      text={PyCode}
      startMarker="# ValidateObject START"
      endMarker="# ValidateObject END"
      language="py"
    />
  </TabItem>

  <TabItem value="js" label="JS/TS Client v2">
    <FilteredTextBlock
      text={TSCode}
      startMarker="// ValidateObject START"
      endMarker="// ValidateObject END"
      language="tsv2"
    />
  </TabItem>
</Tabs>

This makes use of our custom FilteredTextBlock JSX component.

Here, the FilteredTextBlock component loads lines between the startMarker and endMarker from the imported scripts. This allows us to write complete scripts, which may include tests to reduce occurrences of erroneous code examples.

For more information about tests, please see README-tests.md.

In some code examples, the code will be written directly inside the TabItem component, as shown below.

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs groupId="languages">
<TabItem value="py" label="Python">

    ```python
    import weaviate

    client = weaviate.Client("http://localhost:8080")
    ```

</TabItem>
<TabItem value="js" label="JS/TS Client v2">

    ```
    import weaviate from 'weaviate-ts-client';

    const client = weaviate.client({
      scheme: 'http',
      host: 'localhost:8080',
    });
    ```

</TabItem>

... and any other tabs

</Tabs>

Your IDE will not pick up any errors in these examples, so please make sure to test the code in your preferred environment before editing or adding them here.