How to build your own tutorial for the Couchbase Tutorials Site

Introduction

All tutorials are grouped under the tutorials component and are displayed on the tutorials landing page with the metadata highlighted. The metadata combined with the site search is geared to provide quick access to tutorials that may be of interest to the user. The tutorials component is a version-agnostic and each tutorial will list the components and versions used to build the tutorial.

Workspace

This section describes how to set up your workspace.

If you’ve never built the site on your device, complete the Install Antora steps first.

You can use Gulp CLI to preview your site. If you do not have Gulp CLI installed, use the following command to install gulp CLI globally:

npm install -g gulp-cli

Once Antora and Gulp are installed, run through the following steps:

In a new folder, create a new file local-antora-playbook.yml with the following.

site:
  title: Couchbase Docs (Tutorials)
content:
  sources:
  - url: ./tutorials
    branches: HEAD

From that same folder, clone the tutorials repository.
```
git clone https://github.com/couchbase/tutorials.git
```
Build the local preview.
```
gulp
```
You can now open http://localhost:5000/tutorials/index.html in a web browser which should load the tutorials index page. If you notice that the links on the page are broken, don’t worry, it’s happening because we haven’t cloned any tutorial content.

The docs-site readme has more information about using gulp with Antora.

Create a new tutorial from the template

The following steps can be used as the starting point to build your own tutorial.

Clone the tutorial template.

git clone https://github.com/couchbaselabs/tutorial-template

Insert this new source in your local-antora-playbook.yml file.
```
  - url: ./tutorial-template
    branches: HEAD
```
Build and verify your tutorial locally. It should be visible on http://localhost:5000/tutorials/tutorial-template/sample.html
Edit the tutorial template and Metadata Parameters with details of your tutorial.
To submit a change to the site playbooks, you can open a pull request on the tutorials repository to insert your tutorial in staging-antora-playbook.yml and production-antora-playbook.yml.
```
  - url: https://github.com/couchbaselabs/tutorial-template.git
    branches: master
```

The navigation tree for a tutorial is kept in the module with the rest of the content. The following steps describe how to add a new menu item in the left navigation.

Create a new file module-name/pages/_partials/nav.adoc to declare the navigation tree for your tutorial. Insert the following.
```
* Hello World
```
Next, update the root nav in tutorials/modules/ROOT/nav.adoc file to include your tutorial nav.
```
.Nav title for new tutorial
include::module-name:partial$nav.adoc[]
```
Edit module-name/pages/_partials/nav.adoc until you are happy with the output. The contribution guide contains examples of navigation trees.
To submit a change to the root nav.adoc, you can open a pull request on the tutorials repository.

The steps described above apply to all tutorials except userprofile-couchbase-mobile for iOS/Xamarin/Android. The navigation for those tutorials is located in the userprofile-couchbase-mobile repository on the standalone, query, and sync branches.

Add a Tutorial Card

The tutorials index page provides a central location to find tutorials. The following steps describe how to create a card for your tutorial.

Update the index.adoc file to include your new tutorial.

The tutorial information (title, description, components, etc.) must be valid AsciiDoc and follow a pre-defined layout. The following code block describes the AsciiDoc layout. To add or update an existing card, you can submit changes to the index.adoc as a pull request on the tutorials repository.

[.developer]
== Developer (1)

[.title]
=== xref:tutorials:session-storage:install.adoc[Using Couchbase Server as a Session Store] (2)

==== {empty}
[.summary]
An in-depth tutorial that demonstrates how to use Couchbase Server for session storage.
You will learn how to read, write session data and query session data with N1QL for business insights. (3)
[.links]
xref:tutorials:session-storage:aspnet.adoc[ASP.NET Core] (4)
xref:tutorials:session-storage:java.adoc[Java]

===== {empty}

====== Components (5)
* Server 6.0

====== Languages (6)
* C#
* Java

[.metadata]
=== Intermediate (7)

1	The role that this tutorial is primarily written for: `Developer` \| `Architect` \| `Mobile Developer` \| `DevOps`
2	Title to your tutorial, it is recommended for the title length to be under 50 characters. If your tutorial is language agnostic, link the title to the tutorial page. However, if your tutorial contains language (or platform) specific pages, then link the title to the top-level tutorial page that describes the overall tutorial.
3	Abstract for the new tutorial, it is recommended for the abstract length to be under 256 characters.
4	Optional sub-page links (if your tutorial contains language or platform specific pages for example).
5	List the products and their respective versions used to build your tutorial.
6	List the languages applicable to your tutorial.
7	Target level for the tutorial: `Beginner` \| `Intermediate` \| `Advanced`

Publish Your Tutorial

Update the Antora staging and production playbooks in the docs-site repository to include the new tutorial.
```
# Tutorial repositories
- url: https://github.com/couchbaselabs/new-tutorial.git
  branches: master
```
Submit a Pull Request to the docs-site repository with your changes.

That’s it! Your Pull Request will be reviewed and we’ll reach out to you if further changes are needed. Once the PR gets merged, the documentation site will be re-deployed with your tutorial.

For any questions or additional help, please reach out to docs@couchbase.com.

Antora File

The antora.yml file contains the metadata for the build system (Antora). It must contain the following.

name: tutorials (1)
version: 'master' (2)

1	Must be `tutorials`. The new tutorial will identify itself as part of the tutorials component.
2	Must be `'master'`. Specifies the version. The following table lists the metadata parameters used in a tutorial.