docs: add versioning to tutorial (#1413)

* docs: add versioning to tutorial

* docs: address Endilie's comments

docs/tutorial-create-new-site.md

@@ -9,9 +9,13 @@ In this section we'll get our Docusaurus site up and running for local developme
 
 ## Scaffold the Site
 
-1. Execute the `docusaurus-init` command.
+1. Execute the `docusaurus-init` command in your terminal.
 
-The following contents will be created for you in the directory you are in (TODO).
+```sh
+docusaurus-init
+```
+
+The following contents will be created for you in the directory you are in.
 
 ```sh
 ├── Dockerfile

docs/tutorial-create-pages.md

@@ -5,7 +5,7 @@ title: Create Pages
 
 In this section we will learn about creating two new types of pages in Docusaurus, a regular page and a documentation page.
 
-<img alt="Docusaurus process" src="/img/undraw_docusaurus_process.svg" class="docImage"/>
+<img alt="Docusaurus MacBook" src="/img/undraw_docusaurus_tree.svg" class="docImage"/>
 
 ## Creating a Regular Page
 
@@ -33,9 +33,14 @@ function HelloWorld(props) {
 module.exports = HelloWorld;
 ```
 
-2. Go to http://localhost:3000/hello-world (TODO) and you should be able to see the new page.
+2. Go to http://localhost:3000/hello-world and you should be able to see the new page.
 1. Change the text within the `<p>...</p>` to "I'm at F8!". The browser should refresh automatically to reflect the changes.
 
+```diff
+- <p>This is my first page!</p>
++ <p>I'm at F8!</p>
+```
+
 React is being used as a templating engine for rendering static markup. You can leverage on the expressability of React to build rich web content. Learn more about creating pages [here](custom-pages).
 
 <img alt="Docusaurus React" src="/img/undraw_docusaurus_react.svg" class="docImage"/>
@@ -58,13 +63,15 @@ Hello F8! I'm at the Docusaurus classroom session!
 In this session, we learned how Docusaurus makes it really simple to create a website for open source project documentation and get hands on by creating a Docusaurus website.
 ```
 
-3. Go to `sidebars.json` and add `"f8"` after `"doc1"`.
+3. Go to `sidebars.json` and add `"f8"` after `"doc1"`. This ID should be the same one as in the Markdown file above.
 
 ```diff
 {
   "docs": {
-+    "Docusaurus": ["doc1", "f8"],
--    "Docusaurus": ["doc1"],
+    "Docusaurus": [
+      "doc1",
++     "f8"
+    ],
     "First Category": ["doc2"],
     "Second Category": ["doc3"]
   },
@@ -74,7 +81,8 @@ In this session, we learned how Docusaurus makes it really simple to create a we
 }
 ```
 
-4. Navigate to http://localhost:3000/docs/f8. (TODO)
+4. Kill your webserver (<kbd>Cmd</kbd> + <kbd>C</kbd> or <kbd>Ctrl</kbd> + <kbd>C</kbd>) and restart it (with `npm run start`) because a server restart is needed for sidebar changes.
+5. Navigate to http://localhost:3000/docs/f8.
 
 You've created your first documentation page on Docusaurus! The `sidebars.json` is where you specify the order of your documentation pages and in the front matter of the Markdown file is where you provide metadata about that page.
 

docs/tutorial-publish-site.md

@@ -9,7 +9,9 @@ Next we'll learn how to publish the site to the WWW for everyone to browse! For
 
 ## Put the Site Online
 
-In to `website/siteConfig.js`, fill in the following fields:
+Kill the webserver first by pressing Cmd + C or Ctrl + C depending on your operating system.
+
+In `website/siteConfig.js`, fill in the following fields:
 
 ```
 const siteConfig = {
@@ -32,3 +34,5 @@ $ GIT_USER=<GIT_USER> CURRENT_BRANCH=master USE_SSH=true npm run publish-gh-page
 The built code will be pushed to the `gh-pages` branch of your repository.
 
 4. Go to `https://USERNAME.github.io/docusaurus-tutorial/` and view your site in action!
+
+> Note that when you run `npm run start` again, the `baseUrl` will now be part of the path.

docs/tutorial-setup.md

@@ -3,7 +3,7 @@ id: tutorial-setup
 title: Setting Up
 ---
 
-This tutorial is geared at first-time users who want detailed instructions on how to go from zero to a Docusaurus that is versioned. Let's start!
+This tutorial is geared at first-time users who want detailed instructions on how to go from zero to a Docusaurus website that has versions. Let's start!
 
 <img alt="Docusaurus campfire" src="/img/undraw_docusaurus_mountain.svg" class="docImage"/>
 
@@ -14,13 +14,13 @@ Node.js is an environment that can run JavaScript code outside of a web browser
 > Docusaurus' minimum supported Node.js version is Node 8, but more recent versions will work as well.
 
 1. Open your Terminal.
-1. Run the following command to install Node and `npm` the package manager that allows you to install npm modules from your terminal.
+1. If you have `brew` on your OS, run the following command to install Node (a JavaScript runtime that allows you to run JavaScript on the server) and `npm` the package manager (allows you to install npm modules from your terminal).
 
 ```sh
 brew install node
 ```
 
-Alternatively, you can download an installer from the [Node.js homepage][https://nodejs.org/en/].
+Alternatively, you can download an installer from the [Node.js homepage](https://nodejs.org/en/).
 
 ## Check your Node.js installation
 
@@ -49,7 +49,10 @@ We highly recommend you to install Yarn, an alternative package manager that has
 1. Click on **"New Repository"** or go to https://github.com/new.
 1. Name your repository without spaces. For e.g. `docusaurus-tutorial`.
 1. Proceed to create the repository without adding `.gitignore` or a license.
-1. Clone your repository to your local machine:
+
+<img alt="GitHub create repo" src="/img/tutorial-git-clone.png" class="docImage"/>
+
+5. Clone your repository to your local machine:
 
 ```sh
 git clone git@github.com:USERNAME/docusaurus-tutorial.git

docs/tutorial-version.md

@@ -0,0 +1,57 @@
+---
+id: tutorial-version
+title: Add Versions
+---
+
+With an example site deployed, we can now try out one of the killer features of Docusaurus - versioned documentation. Versioned documentation helps to show relevant documention to the users for the current version of the tool they are using and also hide unreleased documentation from users, reducing confusion. Documentation for older versions are also preserved and accessible to users of older versions of the tool even as the latest documentation changes.
+
+<img alt="Docusaurus process" src="/img/undraw_docusaurus_process.svg" class="docImage"/>
+
+## Releasing a Version
+
+Assuming we are happy with the current state of the documentation and we want to freeze it as the v1.0.0 docs. We first run the following command to generate a `versions.js` file, which will be used to list down all the versions of docs in the project.
+
+```sh
+npm run examples versions # yarn examples versions
+```
+
+Next, we run a command with the version we want to create, e.g. 1.0.0,
+
+```sh
+npm run version 1.0.0 # yarn version 1.0.0
+```
+
+This will preserve all documents currently in the `docs` directory and make them available as documentation for version 1.0.0.
+
+Documents in the `docs` directory will be considered part of version next and they are available, for example, at the URL `localhost:3000/<baseUrl>/docs/next/doc1`. Documents from the latest version use the URL `docs/doc1`.
+
+Let's test out that versioning actually works. We can go to `docs/doc1.md` and change the first line of the body:
+
+```diff
+---
+id: doc1
+title: Latin-ish
+sidebar_label: Example Page
+---
+
+- Check the [documentation](https://docusaurus.io) for how to use Docusaurus.
++ This is the latest version of the docs.
+
+## Lorem
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies.
+```
+
+If we go to the `localhost:3000/<baseUrl>/docs/doc1` URL in our browser, realize that it's still showing the previous line. That's because the version we're looking at now is the 1.0.0 version, which has already been frozen in time.
+
+## Next Version
+
+The latest versions of the docs have to be accessed by adding `next` to the URL: `localhost:3000/<baseUrl>/docs/next/doc1`. Note that the version beside the title also changes to `next` when we are on that URL.
+
+A versions page has been created for us at `localhost:3000/<baseUrl>/versions` which shows a list of the current versions of the documentation. See that both `1.0.0` and `master` are being listed here and they correctly link to the respective versions of documentation.
+
+Go ahead and publish your versioned site!
+
+## Wrap Up
+
+That's all folks! In this short tutorial you have experienced how easy it was to create a documentation website from scratch and making versions for them. There are many more things you can do with Docusaurus, such as adding a blog, search and translations. Check out the Guides section for more.

packages/docusaurus-1.x/examples/versions/pages/en/versions.js

@@ -35,7 +35,14 @@ function Versions(props) {
               <tr>
                 <th>{latestVersion}</th>
                 <td>
-                  <a href="">Documentation</a>
+                  {/* You are supposed to change this href where appropriate
+                        Example: href="<baseUrl>/docs(/:language)/:id" */}
+                  <a
+                    href={`${siteConfig.baseUrl}${siteConfig.docsUrl}/${
+                      props.language ? props.language + '/' : ''
+                    }doc1`}>
+                    Documentation
+                  </a>
                 </td>
                 <td>
                   <a href="">Release Notes</a>
@@ -53,16 +60,24 @@ function Versions(props) {
               <tr>
                 <th>master</th>
                 <td>
-                  <a href="">Documentation</a>
+                  {/* You are supposed to change this href where appropriate
+                        Example: href="<baseUrl>/docs(/:language)/next/:id" */}
+                  <a
+                    href={`${siteConfig.baseUrl}${siteConfig.docsUrl}/${
+                      props.language ? props.language + '/' : ''
+                    }next/doc1`}>
+                    Documentation
+                  </a>
                 </td>
                 <td>
-                  <a href="">Release Notes</a>
+                  <a href={repoUrl}>Source Code</a>
                 </td>
               </tr>
             </tbody>
           </table>
           <p>Other text describing this section.</p>
           <h3 id="archive">Past Versions</h3>
+          <p>Here you can find previous versions of the documentation.</p>
           <table className="versions">
             <tbody>
               {versions.map(
@@ -71,9 +86,14 @@ function Versions(props) {
                     <tr>
                       <th>{version}</th>
                       <td>
-                        {/* You are supposed to fill this href by yourself 
-                        Example: href={`docs/${version}/doc.html`} */}
-                        <a href="">Documentation</a>
+                        {/* You are supposed to change this href where appropriate
+                        Example: href="<baseUrl>/docs(/:language)/:version/:id" */}
+                        <a
+                          href={`${siteConfig.baseUrl}${siteConfig.docsUrl}/${
+                            props.language ? props.language + '/' : ''
+                          }${version}/doc1`}>
+                          Documentation
+                        </a>
                       </td>
                       <td>
                         <a href={`${repoUrl}/releases/tag/v${version}`}>

website-1.x/sidebars.json

@@ -27,7 +27,8 @@
       "tutorial-setup",
       "tutorial-create-new-site",
       "tutorial-create-pages",
-      "tutorial-publish-site"
+      "tutorial-publish-site",
+      "tutorial-version"
     ]
   }
 }