docs: enable versioning and add 0.20 snapshot

.github/workflows/docs.yaml

@@ -41,6 +41,8 @@ jobs:
               run: |
                   # install project deps
                   yarn
+                  # update next docs reference
+                  yarn update-docs
                   # go to website dir
                   cd website
                   # install website deps

package.json

@@ -17,7 +17,8 @@
         "clean": "rimraf dist",
         "build": "yarn clean && tsc && tsc -p tsconfig.typechecking.json",
         "postpack": "rimraf oclif.manifest.json",
-        "prepack": "yarn build && oclif manifest && oclif readme && oclif readme --readme-path=docs/reference.md",
+        "prepack": "yarn build && oclif manifest && oclif readme && yarn update-docs",
+        "update-docs": "oclif readme --readme-path=docs/reference.md",
         "postinstallDev": "yarn build && node ./bin/run.js check-version && node ./dist/lib/community.js"
     },
     "files": [

website/docusaurus.config.js

@@ -1,5 +1,7 @@
 const { config } = require('@apify/docs-theme');
+
 const { externalLinkProcessor } = require('./tools/utils/externalLink');
+const versions = require('./versions.json');
 
 const { absoluteUrl } = config;
 /** @type {Partial<import('@docusaurus/types').DocusaurusConfig>} */
@@ -23,35 +25,38 @@ module.exports = {
                     title: 'Apify CLI',
                     items: [
                         {
-                            to: 'docs',
+                            type: 'doc',
+                            docId: 'index',
                             label: 'Docs',
                             position: 'left',
                             activeBaseRegex: 'docs(?!/changelog|/reference)',
                         },
                         {
-                            to: 'docs/reference',
+                            type: 'doc',
+                            docId: 'reference',
                             label: 'Reference',
                             position: 'left',
-                            activeBaseRegex: 'docs/reference',
+                            activeBaseRegex: 'reference',
                         },
                         {
-                            to: 'docs/changelog',
+                            type: 'doc',
+                            docId: 'changelog',
                             label: 'Changelog',
                             position: 'left',
-                            activeBaseRegex: 'docs/changelog',
+                            activeBaseRegex: 'changelog',
                         },
                         {
                             href: 'https://github.com/apify/apify-cli',
                             label: 'GitHub',
                             position: 'left',
                         },
-                        // {
-                        //     type: 'docsVersionDropdown',
-                        //     position: 'left',
-                        //     className: 'navbar__item', // fixes margin around dropdown - hackish, should be fixed in theme
-                        //     dropdownItemsBefore: [],
-                        //     dropdownItemsAfter: [],
-                        // },
+                        {
+                            type: 'docsVersionDropdown',
+                            position: 'left',
+                            className: 'navbar__item', // fixes margin around dropdown - hackish, should be fixed in theme
+                            dropdownItemsBefore: [],
+                            dropdownItemsAfter: [],
+                        },
                     ],
                 },
             },
@@ -78,6 +83,6 @@ module.exports = {
     plugins: [
         ...config.plugins,
     ],
-    themeConfig: config.themeConfig,
+    themeConfig: { ...config.themeConfig, versions },
     staticDirectories: ['node_modules/@apify/docs-theme/static', 'static'],
 };

website/versioned_docs/version-0.20/index.md

@@ -0,0 +1,22 @@
+---
+title: Apify CLI
+---
+
+<a href="https://www.npmjs.com/package/apify-cli"><img src="https://badge.fury.io/js/apify-cli.svg" alt="npm version" loading="lazy" /></a>
+<a href="https://travis-ci.com/apify/apify-cli?branch=master"><img src="https://travis-ci.com/apify/apify-cli.svg?branch=master" loading="lazy" alt="Build Status" /></a>
+
+Apify command-line interface (Apify CLI) helps you create, develop, build and run
+[Apify Actors](https://apify.com/actors),
+and manage the Apify cloud platform from any computer.
+
+Apify Actors are cloud programs that can perform arbitrary web scraping, automation or data processing job.
+They accept input, perform their job and generate output.
+While you can develop Actors in an online IDE directly in the [Apify web application](https://console.apify.com/),
+for complex projects it is more convenient to develop Actors locally on your computer
+using <a href="https://github.com/apify/apify-sdk-js">Apify SDK</a>
+and only push the Actors to the Apify cloud during deployment.
+This is where the Apify CLI comes in.
+
+Note that Actors running on the Apify platform are executed in Docker containers, so with an appropriate `Dockerfile`
+you can build your Actors in any programming language.
+However, we recommend using JavaScript / Node.js, for which we provide most libraries and support.

website/versioned_docs/version-0.20/installation.md

@@ -0,0 +1,189 @@
+---
+title: Installation
+description: Learn how to install Apify CLI, and how to create, run, and manage Actors through it.
+sidebar_label: Installation
+---
+
+## Installation
+
+You can install Apify CLI either using [Homebrew package manager](https://brew.sh) on macOS or Linux or using NPM on all platforms including Windows.
+
+### Via Homebrew
+
+Run the following command:
+
+```bash showLineNumbers
+brew install apify-cli
+```
+
+### Via NPM
+
+First, make sure you have [Node.js](https://nodejs.org) version 18 or higher with NPM installed on your computer:
+
+```bash showLineNumbers
+node --version
+npm --version
+```
+
+Install or upgrade Apify CLI by running:
+
+```bash showLineNumbers
+npm -g install apify-cli
+```
+
+If you receive a permission error, read npm's [official guide](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) on installing packages globally.
+
+Alternatively, you can use [Node Version Manager (nvm)](https://github.com/nvm-sh/nvm) and install Apify CLI only into a selected user-level Node version without requiring root privileges:
+
+```bash showLineNumbers
+nvm install 18
+nvm use 18
+npm -g install apify-cli
+```
+
+After using either of these methods , verify that Apify CLI was installed correctly by running:
+
+```bash showLineNumbers
+apify --version
+```
+
+which should print something like:
+
+```bash showLineNumbers
+apify-cli/0.19.1 linux-x64 node-v18.17.0
+```
+
+## Basic Usage
+
+The following examples demonstrate the basic usage of Apify CLI.
+
+### Create a New Actor from Scratch
+
+```bash showLineNumbers
+apify create my-hello-world
+```
+
+First, you will be prompted to select a template with the boilerplate for the Actor, to help you get started quickly.
+The command will create a directory called `my-hello-world` that contains a Node.js project
+for the Actor and a few configuration files.
+
+### Create a New Actor from Existing Project
+
+:::tip Automatic Actor directory initialization
+When you create an Actor using the `apify create` command, the directory will already be initialized.
+:::
+
+```bash showLineNumbers
+cd ./my/awesome/project
+apify init
+```
+
+This command will only set up local Actor development environment in an existing directory,
+i.e. it will create the `.actor/actor.json` file and `apify_storage` directory.
+
+Before you can run your project locally using `apify run`, you have to set up the right start command in `package.json` under scripts.start. For example:
+
+```json showLineNumbers
+{
+    ...
+    "scripts": {
+        "start": "node your_main_file.js",
+    },
+    ...
+}
+```
+
+You can find more information about by running `apify help run`.
+
+### Run the Actor Locally
+
+```bash showLineNumbers
+cd my-hello-world
+apify run
+```
+
+This command runs the Actor on your local machine.
+Now's your chance to develop the logic - or magic :smirk:
+
+### Login with your Apify account
+
+```bash showLineNumbers
+apify login
+```
+
+Before you can interact with the Apify cloud, you need to [create an Apify account](https://console.apify.com/)
+and log in to it using the above command. You will be prompted for
+your [Apify API token](https://console.apify.com/settings/integrations).
+
+:::note API token save directory
+The command will store the API token and other sensitive information to `~/.apify`.
+:::
+
+### Push the Actor to the Apify Cloud
+
+```bash showLineNumbers
+apify push
+```
+
+This command uploads your project to the Apify cloud and builds an Actor from it. On the platform, Actor needs to be built before it can be run.
+
+### Run an Actor on the Apify Cloud
+
+```bash showLineNumbers
+apify call
+```
+
+Runs the Actor corresponding to the current directory on the Apify Platform.
+
+This command can also be used to run other Actors, for example:
+
+```bash showLineNumbers
+apify call apify/hello-world
+```
+
+### So what's in this `.actor/actor.json` File?
+
+This file associates your local development project with an Actor on the Apify Platform.
+It contains information such as Actor name, version, build tag and environment variables.
+Make sure you commit this file to the Git repository.
+
+For example, `.actor/actor.json` file can look as follows:
+
+```json showLineNumbers
+{
+  "actorSpecification": 1,
+  "name": "name-of-my-scraper",
+  "version": "0.0",
+  "buildTag": "latest",
+  "environmentVariables": {
+    "MYSQL_USER": "my_username",
+    "MYSQL_PASSWORD": "@mySecretPassword"
+  },
+  "dockerfile": "./Dockerfile",
+  "readme": "./ACTOR.md",
+  "input": "./input_schema.json",
+  "storages": {
+    "dataset": "./dataset_schema.json"
+  }
+}
+```
+
+**`Dockerfile` field**
+
+If you specify the path to your Docker file under the `dockerfile` field, this file will be used for Actor builds on the platform. If not specified, the system will look for Docker files at `.actor/Dockerfile` and `Dockerfile` in this order of preference.
+
+**`Readme` field**
+
+If you specify the path to your readme file under the `readme` field, the readme at this path will be used on the platform. If not specified, readme at `.actor/README.md` and `README.md` will be used in this order of preference.
+
+**`Input` field**
+
+You can embed your [input schema](https://docs.apify.com/actors/development/input-schema#specification-version-1) object directly in `actor.json` under `input` field. Alternatively, you can provide a path to a custom input schema. If not provided, the input schema at `.actor/INPUT_SCHEMA.json` and `INPUT_SCHEMA.json` is used in this order of preference.
+
+**`Storages.dataset` field**
+
+You can define the schema of the items in your dataset under the `storages.dataset` field. This can be either an embedded object or a path to a JSON schema file. You can read more about the schema of your Actor output [here](https://docs.apify.com/actors/development/output-schema#specification-version-1).
+
+:::note Migration from deprecated config "apify.json"
+Note that previously, Actor config was stored in the `apify.json` file that has been deprecated. You can find the (very slight) differences and migration info in [migration guidelines](https://github.com/apify/apify-cli/blob/master/MIGRATIONS.md).
+:::