Document content
In this section, you will find the Markdown writing rules for creating your content documentation.
To document a Stack or Starter created by the StackSpot Platform, you must generate folders locally. To do this, follow the steps below:
Step 1.: Log in to the STK CLI:
stk login
Step 2.: Run the command below to create the Stack manifest:
For Stack
stk create stack --from studio-name/stack-name
For Starter
stk create starter studio-name/stack-name
Step 3.: Answer the terminal questions
? Name your stack: name of your Stack.
? Version: 1.0.0
? Do you want to start a git repository? Yes/No
? Stack description: describe the purpose of the Stack.
Step 4.: Edit the .md file in the /docs/en_br and /docs/en_us folders with the content you want to document;
Step 5. Run the command below in your Stack folder:
stk update doc --studio <studio-slug>
Your Stack or Starter documentation has been successfully published on the StackSpot Platform.
To update documentation, follow the steps below:
Step 1: Log in to the STK CLI:
stk login
Step 2: Write the changes you want to make to the .md file;
Step 3. Run one of the commands below:
stk update doc --studio <studio-slug>
Done. The changes have been subscribed to the documentation.
Follow the rules for documenting Stack, Action, Plugin, and Starter in StackSpot.
Titles
Organize the sections hierarchically, with main headings (h1) for the larger sections and secondary headings (h2 and h3) for the subsections. This helps the user understand the structure of the content and easily navigate through the different parts.
Also, use very descriptive titles that summarize the content of each section.
StackSpot documentation titles accept the following syntaxes:
# A first-level heading
## A second-level heading
### A third-level heading
Text style
| Style | Syntax | Example | Output |
|---|---|---|---|
| Bold | ** ** or __ __ | This is bold text | This is bold text |
| Italic | * * or _ _ | _ This text is italicized _ | This text is italicized |
| Strike through | ~~ ~~ | ~~ This was mistaken text ~~ | |
| Bold and italics aligned | ** ** and _ _ | This text is _ extremely _ important | This text is extremely important |
| All in bold and italics | ******* ******* | All this text is important | All this text is important |
| Subscribed | < sub > < /sub > | This is a < sub >subscript< /sub > text | This is a subscript text |
| Overwritten | < sup > < /sup > | This is a < sup >superscript< /sup > text | This is a superscript text |
Reference text
To cite a text, follow the pattern below:
> Insert your text here.
See the example below:
Insert your text here.
Code block
You can include code or command in a sentence with single quotes (`), for example:
git status
To add a code or text in a block, use triple backticks (```).
# code block<br/>
print '3 backticks or'<br/>
print 'indent four spaces'<br/>
Links
To add an embedded link, insert the link text in square brackets [ ] and put the URL in brackets ( ).
See the example below:
This site was built using [GitHub Pages](https://pages.github.com/).
You can also link directly to a section of an interpreted file by hovering over the section title to expose the symbol.
Paragraph
To create a paragraph by leaving a blank line between the lines of text.
Footnotes
To add footnotes to your content, use the syntax in square brackets. See the example below:
Here is a simple footnote[^1].
A footnote can also have multiple lines[^2].
[^1]: My reference.
[^2]: To add line breaks within a footnote, prefix new lines with 2 spaces.
This is a second line.
Image
To add images to your documentation, follow the example below:
Remember that for everyone to have access to it, you need to add a suitable description about it:
For a good image description:
-
Analyze the image and identify the key elements that need to be described, such as people, objects, context, and essential visual information.
-
Write a concise description that conveys all the relevant information in the image. Avoid subjective language or personal interpretations. Be objective and clear.
Lists
Numbered lists
To sort a list, put a number in front of each line. See the example below:
1. James Madison
2. James Monroe
3. John Quincy Adams
Bullet lists
To create a bullet list using the GitHub Web editor or a text editor that uses a monospaced font, such as Visual Studio Code, follow the steps below:
- Type space characters in front of the aligned list item until the list marker character (**- or ***) is directly below the first text character in the item above it.
See the example below:
1. First list item
- First nested list item
- Second nested list item
Emoji
To add an emoji to your document, type :EMOJICODE:, a colon (:), and then the emoji's name. For more information, see the list of the available emojis.
See the example below:
@octocat :+1: This PR looks excellent - it's ready to merge! :shipit:
Alerts
'Alerts' are a valuable tool to highlight important information in a text block. You can use them to draw attention to critical details. To use alerts, you can explore the available options listed below:
> [!NOTE]
>> Highlights information that users should consider, even when skimming.
> [!INFO]
>> Important information about some features.
> [!TIP]
>> Information that serves as a tip for the user.
> [!IMPORTANT]
>> Crucial information necessary for users to succeed.
> [!DANGER]
>> Content that requires user care.
> [!WARNING]
>> Critical content demanding immediate user attention due to potential risks.
See the examples below:
Hide content with comments
On GitHub, you can hide markdown content by putting the content in an HTML comment.
Table
You can include tables of contents. See the template below:
| Rank | Languages |
|----- |-----------|
| 1| Javascript|
| 2| Python |
| 3| SQL |
Documentation template
Complete this template so that users can utilize your content. The information will appear on the Plugin, Stack, Starter, and Action pages in the StackSpot Portal.
# **Name {{ Plugin/Stack/Action/Starter }}**
Write a clear and brief description of the content {{ of the Plugin/Action/Stack/Starter }}.
Example:
> This Plugin contains instructions on how to fill in the information to use the Plugins on the StackSpot platform.
## **Pre-requisites**
- Describe in a list all the items and actions required before applying {{ the Plugin or creating Stack/Action/Starter }}.
Example:
1. Install dependencies;
2. Create the configuration file;
3. Create the **template** folder.
## **Use**
Describe the steps for the user to use Plugin/Stack/Action/Starter:
### Entries
### Methods
### Resources
### Add the dependencies of your Plugin/ content if necessary.
Example:
### Entry
In your application's folder, apply **plugin-doc-template** to populate the following files:
1. Run the command:
`stk apply plugin /Users/Home/plugin-doc-template`
2. Fill out the Plugin information following the x file template examples;
## **Release Notes**
This section is only necessary if you publish a new Plugin/Stack/Action/Starter version. Add what has been modified or added.
Example:
## **plugin-doc-template v1.0.0**
### Features
Added new templates.