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.

Create a new tutorial from the template

This following steps can be used as the starting point to build your own tutorial for the Couchbase Tutorials site.

  1. Clone the tutorial template.

    git clone https://github.com/couchbaselabs/tutorial-template
  2. Edit the tutorial template and Metadata Parameters with details of your tutorial.

  3. Build and verify your tutorial locally.

    1. Update the local Antora playbook (such as staging-antora-playbook.yml) file in the docs-site repo to include the new tutorial repo.

        # Tutorial repositories
        - url: https://github.com/couchbaselabs/tutorial-template.git
          branches: master

      See contribute/test-site.adoc for information on how to test your changes locally.

  4. Push the new tutorial repository to GitHub under couchbase or couchbaselabs organizations.

Update the Tutorials Left Navigation

  1. Add your new tutorial to the tutorials site nav.

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

    .Nav title for new tutorial
    Unresolved include directive in modules/tutorial-template/pages/sample.adoc - include::new-tutorial-component:partial$nav.adoc[]
  2. To submit a change to nav.adoc, you can open a pull request on the tutorials repository.

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.

  1. 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

  1. 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
  2. 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.