All Products
Search
Document Center

Cloud Shell:Write a tutorial

Last Updated:Jun 24, 2024

You can write tutorials in Cloud Shell and publish the tutorials to a remote Git repository. Users can read the tutorials to get started with your project.

In tutorial mode of Cloud Shell, users can click command lines in the documentation to run the command lines in Cloud Shell.

Step 1: Create a tutorial file

To create a tutorial file, perform the following steps:

  1. Create a folder in Cloud Shell for storing the tutorial file.

    Example

    mkdir tutorials
  2. Create a Markdown file in the root directory of the folder. For example, run the following command to create the tutorial.md file:

    touch tutorial.md

Step 2: Write a tutorial

You can write a tutorial by using the Markdown syntax. When you write a tutorial, take note of the following rules:

  • Use a number sign (#) to create a level 1 heading. The level 1 heading is the title of the tutorial. You can create only one level 1 heading in a tutorial.

  • Use two number signs (##) to create a level 2 heading. The level 2 heading is the title of a step.

  • Write code by using the Markdown syntax. Cloud Shell renders your code into code blocks that have Execute icons in the tutorial. Users can click the Execute icon of a code block to copy the code block to the editor of Cloud Shell.

    ```bash
    aliyun help
    ```    
  • Use the following directory instruction of Cloud Shell to generate a directory structure for your tutorial:

    <tutorial-nav></tutorial-nav>
  • Use the following open file instruction of Cloud Shell to add file links to your tutorial. Users can click links in your tutorial to open the files to which the links point in the editor of Cloud Shell.

    <tutorial-editor-open-filefilePath="path/test.md>Open File</tutorial-editor-open-file>

    To add the link of a file to your tutorial, store the file in the $HOME directory or a subdirectory of $HOME. You can set filePath in the instruction to the absolute or relative path of the file. The relative path specifies the location of the file relative to $HOME.

The following sample code provides an example on how to create a tutorial. You can use the Vim editor or the editor of Cloud Shell to write your tutorial.

# Use Alibaba Cloud CLI to manage cloud resources.

## View the help information of Alibaba Cloud CLI.
```bash
aliyun help
```
### First
Notes
### Next
Notes
```bash
echo world
```
## Congratulations! You completed the tutorial!
Congratulations! You completed the tutorial on how to use Alibaba Cloud CLI! 

Step 3: Publish the tutorial

To publish the tutorial, perform the following steps:

  1. Before you publish the tutorial, run the following command to test the tutorial:

    teachme tutorial.md
  2. After your tutorial passes the test, run the git push command of Cloud Shell to upload your tutorial from an on-premises Git repository to a remote Git repository. The folder in which you store the tutorial is the on-premises Git repository.

    Note

    Upload your tutorial to a remote repository that can be accessed over the Internet. Otherwise, users who read your tutorial may be unable to clone the remote repository to Cloud Shell.