Skip to main content
Version: v4.4.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 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 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 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 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 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.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.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 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 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 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 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 import stack <URL-of-your-stack> command.

Was this page helpful?