Skip to main content
Version: v4.5.0

Migrate your existing project to a Stack

Context​

In this tutorial, you will see a pre-existing project to show you how to migrate your current project to a Stack. You can do that by splitting your project into Templates and Plugins.

The project's example has the following structure:

DOCUMENTATION
  |__ INDEX.md
  |__ topic1
       |__ doc1.md
       |__ doc2.md
  |__ topic2
       |__ doc1.md
       |__ doc2.md

In this example you can see a documentation folder with:

  • An index with documentation references on each topic.
  • A folder structure where each documentation topic is divided by a new folder with the documentation.

Divide the project into Template and Plugins​

In the example structure above, you can define two things:

  1. The base Template of the project.
  2. The Plugins you will apply in your application, you created it using the Template.

Before you begin​

info
1. What is a Template?
It is the skeleton of a Stack that contains the minimum to make an application. It is an application model that you use to build a project.

In this example, the "basic structure" for a Template is:

DOCUMENTATION
  |__ INDEX.md

This structure has the basics to maintain documentation:

  1. A folder with the project's name;
  2. An INDEX.md file with references to the documentation files.

Now the Template is defined.

info
2. What is a Plugin?
A Plugin is a Stack extension that allows you to add new capabilities to the base Template. You can include source code, import libraries, and even run complex commands and operations to add capabilities to a Stack.

In this example, the Template's extensions are:

  • New folders and documents that can be added to the documentation;
  • You can include new document references in the INDEX.md.

This Plugin adds new topics, and their respective files, and updates the INDEX.md

After applying the Plugin, the structure of the project should be:

DOCUMENTATION
  |__ INDEX.md
  |__ topic1
       |__ doc1.md
       |__ doc2.md

Create a Stack and a Template​

Prerequisites​

  • Install STK CLI;
  • Create a folder to create your Stack.
  • In this tutorial, the folder will be ~/demo.

Step 1. Go to the folder where you want to create your Stack​

cd ~/demo

Step 2. Create your Stack to have your Template and Plugins​

stk-legacy create stack docs-stack

Your created a Stack in the current folder.

Step 3. Create your Template using the STK CLI​

Go to the Stack folder you created in the previous step:

cd ~/demo/docs-stack

Create your Template inside the Stack:

stk-legacy  create template docs-template

Add the Template's description:

? Template description: Basic Template for a documentation project

Creating your Template now:

template docs-template successfully created!

Step 4. Edit the Template to include the basic structure previously defined​

Go to the folder where the Template was created:

~/demo/docs-stack/docs-template

Inside the folder there is a templates folder and a template.yaml file:

Docs-template structure:

docs-template
   |_template.yaml
   |_templates

Inside the templates folder, you have to include the files to be part of the Template. In the templates folder, include the files, they will be part of the Template.

Step 5. Copy the project's base files to the templates folder of the docs-template​

docs-template
   |_template.yaml
   |_templates
         |_INDEX.md

You need to create an empty INDEX.md file in the templates folder of the docs-template.

Step 6. Test this Template, create an application with the stk-legacy create app command, with the-pflag to use the Template's local path​

Go back to the ~/demo folder:

cd ~/demo

Create an application using the local Template. You have to create the application outside the Stack folder:

stk-legacy create app documentation -p ~/demo/docs-stack/docs-template

Your application will be created inside the demo file under the documentation name.

Check the application's structure you created. You can see the INDEX.md file was created correctly:

documentantion
   |_INDEX.md
   |_stk.yaml //App Control File
   |_.gitignore

Done! Your created your application from the basic structure of a Template.

Create the Stack's Plugins​

After the Template was defined and created in your Stack, you can create Plugins to add new capabilities to your application.

Context​

This Plugin adds a folder to the documentation project with the name received by an input. It should add new files within this created folder. In addition, the Plugin should edit the existing INDEX.md file to add the reference to the created file.

Step 1. Go to the Stack folder​

cd ~/demo/docs-stack

Step 2. Create the Plugin structure using STK CLI​

stk-legacy create plugin add-docs-plugin

Add a description to your Plugin:

? Plugin description: This Plugin adds new files and folders to the documentation. It also updates the index.

Check the Plugin's structure you created, it needs to be like this:

 add-docs-plugin
    |_docs //folder for the plugin's documentation
    |_templates // A place where the plugin files are located
    |_plugin.yaml //Plugin configuration file
    |_plugin.png //Image that will be displayed on the website
    |_.gitignore

Step 3. Edit the plugin.yaml file to add the inputs referring to the folder's name you are going to add, and the name of the file​

You can remove the example inputs from plugin.yaml and add two new ones:

 - label: Name of documents folder
   type: text
   name: folder_name
   required: true
 - label: Name of document file
   type: text
   name: file_name
   required: true

The final file will look like this:

name: add-docs-plugin
description: This Plugin adds new files and folders to the documentation. It also updates the index.
display-name: add-docs-plugin
picture: plugin.png
category: backend # Ref: https://docs.legacy.stackspot.com/latestcreators-guide/yaml/#category
compatibility:
 - java
 - spring
about: docs/about.md
usage: docs/usage.md
use-case: docs/use-case.md
implementation: docs/implementation.md
technologies: # Ref: https://docs.legacy.stackspot.com/latestcreators-guide/yaml/#technologies
 - "Api"
types:
 - app
inputs:
 - label: Name of doc folder
   type: text
   name: folder_name
   required: true
 - label: Name of document file
   type: text
   name: file_name
   required: true

Step 4. Add the documentation folder structure, and it is created when you apply the Plugin​

Add a folder named {{folder_name}} in the templates folder of add-docs-plugin Plugin:

 add-docs-plugin
    |_templates 
  |_{{folder_name}}

Add the {{file_name}}.md file to the {{folder_name}} folder:

 add-docs-plugin
   |_templates 
  |_{{folder_name}}
   |_ {{file_name}}.md

Edit the file {{file_name}}.md to contain in its header the file's name:

### {{file_name}}

After these changes, when you apply a Plugin with the stk-legacy apply plugin command, it creates a new folder with the given name in the input: "folder_name". Also, it creates a new .md file in this folder with the name informed in the input "file_name". The file will have the "file_name" value in its title.

Step 5. Add anINDEX.mdfile to the Plugin'stemplatesfolder and modify it to include the reference to the files added by the Plugin​

Add the file INDEX.md to the root of the plugin's templates folder.

add-docs-plugin
|_templates 
 |_INDEX.md
 |_{{folder_name}}
    |_{{file_name}}.md

When applying this Plugin, the contents of the INDEX.md file will be merged with the original INDEX.md content.

Change the Plugin's INDEX.md file, it was created in the previous step, to include the reference to the added files. Copy and paste the content below into your Plugin's INDEX.md file. You do not need to change any values.

INDEX.md do plugin:

<br>[{{file_name}}](/{{folder_name}}/{{file_name}})<br>

In subsequent Plugin applications, the INDEX.md file contents will be merged.

With these modifications the Plugin is ready. And now you can test it.

Apply the Plugin in your application​

Apply the Plugin to the application. You created it earlier.

Step 1. Go to the application folder:

cd ~/demo/documentation

Step 2. Use STK CLI to apply the Plugin to your Stack using the -p flag and the absolute path to your Plugin's folder.

stk-legacy apply plugin -p ~/demo/docs-stack/add-docs-plugin

Enter the name of the folder: 

 ? Name of documents folder: topic1

Add the file's name:

 ? Name of document file: doc1.

The Plugin will be applied.

Step 3. Check the application's structure

The INDEX.md file was updated with the reference file you added:

INDEX.md from the application:

<br>[doc01](/topic1/doc01)<br>

The application's structure will look like the one below:

documentation
  |__ INDEX.md
   |__ topic1
         |__ doc1.md

The doc1.md file will have the following content:

### doc1

You have just applied the Plugin!

info

It is possible to apply the same Plugin several times to the same application. You can create several folders or files with a predetermined pattern and add this information to the INDEX.md too.

Creating a Stackfile​

After creating your Template and Plugin, you can create a Stackfile. It makes it easier to use the Template and Plugin together.

info

What is a Stackfile? They are bundles. It's like a set of predefined Templates and Plugins from a Stack that will be applied with the stk-legacy create app command.

Step 1. Go to your Stack folder​

cd ~/demo/docs-stack

Step 2. Go to the Stackfiles folder​

cd stackfiles

Step 3. Create you Stackfile running the following command​

stk-legacy create stackfile docs-stackfile

Step 4. Edit the docs-stackfile.yaml file to include your Template and Plugin's data​

The stackfile will look like this:

type: app
description: "Creates the basic structure of a documentation folder"
template: docs-stack/docs-template
plugins:
- plugin: docs-stack/add-docs-plugin
  inputs:
    folder_name: use_case
    file_name: use_case

In this Stackfile, the Template will be used and a folder named use_case will be created with a use_case.md file. Your Stack can have multiple Stackfiles, with different inputs.

Upload your Stack to a GitHub repository​

Now that you created your Stack, Template, Plugin, and Stackfile, you can upload your Stack to GitHub so you can share it with others.

1. To upload your Stack to GitHub, go to the Stack directory:

cd ~/demo/docs-stack

2. Set your repository as remote:

git remote add origin <your-repository-url>

3. Add the files and commit:

git add --all
git commit --message <mensagem-commit>

4. Send your Stack:

git push

Now your Stack is available, users need to run the stk-legacy import stack <URL-of-your-stack> command.

Was this page helpful?