Pular para o conteúdo principal

Documentar conteúdo

Nesta seção, você encontra as regras de escrita de Markdown para criar a sua documentação de conteúdo.


Atenção!

Para documentar uma Stack ou um Starter criados pela Plataforma da StackSpot, você precisa gerar pastas localmente. Para isso, siga os passos:

Passo 1. Faça login no STK CLI:

stk login

Passo 2. Execute o comando para criar o manifesto da Stack:

  • Para Stack:
stk create stack --from studio-name/stack-name
  • Para Starter:
stk create starter studio-name/stack-name

Passo 3. Responda as perguntas do terminal

? Nomeie sua stack: nome da sua Stack.
? Versão: 1.0.0
? Você deseja iniciar um repositório git? Yes/No
? Descrição da stack: descreva o objetivo da Stack.

Passo 4. Edite o arquivox .md nas pastas /docs/pt_br e /docs/en_us com o conteúdo que você quer documentar;

Passo 5. Execute o comando na pasta da sua Stack:

stk update doc --studio <studio-slug>

Pronto! Sua documentação de Stack ou Starter foi publicada na Plataforma da StackSpot.

Informação Complementar

Para atualizar uma documentação, siga os passos:

Passo 1. Faça login no STK CLI:

stk login

Passo 2. Escreva as mudanças que você quer fazer no arquivo .md;

Passo 3. Execute o comando:

stk update doc --studio <studio-slug>

Pronto. As mudanças foram adicionadas na documentação.

Confira as regras para documentar Stack, Action, Plugin e Starter na StackSpot.

Títulos

Organize as seções de forma hierárquica, com títulos principais (h1) para as seções mais amplas e títulos secundários (h2 e h3) para as subseções. Isso ajuda o usuário a entender a estrutura do conteúdo e a navegar facilmente pelas diferentes partes.

Além disso, utilize títulos bem descritivos que resumem o conteúdo de cada seção.

Os títulos da documentação da StackSpot aceitam as seguintes sintaxes:

# A first-level heading
## A second-level heading
### A third-level heading

Estilo do texto

EstiloSintaxeExemploSaída
Negrito** ** ou __ __This is bold textThis is bold text
Itálico* * ou _ __ This text is italicized _This text is italicized
Tachado~~ ~~~~ This was mistaken text ~~This was mistaken text
Negrito e itálico alinhado** ** e _ _This text is _ extremely _ importantThis text is extremely important
Todo em negrito e itálico******* *******All this text is importantAll this text is important
Subscrito< sub > < /sub >This is a < sub >subscript< /sub > textThis is a subscript text
Sobrescrito< sup > < /sup >This is a < sup >superscript< /sup > textThis is a superscript text

Texto de referência

Para citar um texto, siga o padrão:

> Insert your text here.

Confira o exemplo:

Insira seu texto aqui.

Bloco de código

Você pode incluir um código ou um comando em uma frase com aspas simples (`), como por exemplo:

-git status

Para formatar um código ou texto em um bloco use aspas triplas (```).

# code block<br/>
print '3 backticks or'<br/>
print 'indent 4 spaces'<br/>

Para adicionar um link embutido inserindo o texto do link entre colchetes [ ] e colocando a URL entre parênteses ( ).

Confira o exemplo:

This site was built using [GitHub Pages](https://pages.github.com/).
Informação Complementar

Você também pode vincular um link diretamente a uma seção de um arquivo interpretado, passando o mouse sobre o título da seção para expor símbolo.

Parágrafo

Para criar um parágrafo deixando uma linha em branco entre as linhas de texto.

Notas de rodapé

Para adicionar notas de rodapé ao seu conteúdo use a sintaxe entre colchetes. Confira o exemplo:

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.

Imagem

Para adicionar imagens na sua documentação, siga o exemplo:

![Alt ou título da imagem](URL da imagem)

Lembre-se de que, para que todos tenham acesso à ela, é preciso adicionar uma boa descrição sobre:

Dica!

Para uma boa descrição de imagens:

  • Analise a imagem e identifique os elementos-chave que precisam ser descritos. Isso pode incluir pessoas, objetos, contexto e qualquer informação visual importante.

  • Escreva uma descrição concisa que transmita todas as informações relevantes da imagem. Evite linguagem subjetiva ou interpretações pessoais. Seja objetivo e claro.

Listas

Listas ordenadas

Para ordenar uma lista, coloque um número na frente de cada linha. Confira o exemplo:

1. James Madison
2. James Monroe
3. John Quincy Adams

Listas alinhadas

Para criar uma lista alinhada usando o editor Web do GitHub ou um editor de texto que use uma fonte monoespaçada, como o Visual Studio Code, siga o passo:

  • Digite os caracteres de espaço na frente do item de lista alinhado até que o caractere do marcador da lista (**- ou ***) fique diretamente do primeiro caractere do texto no item acima dele.

Confira o exemplo:

1. First list item
- First nested list item
- Second nested list item

Emoji

Para adicionar um emoji à escrita digite :EMOJICODE:, dois pontos (:) e, em seguida, o nome do emoji. Confira a lista de emojis disponíveis para uso.

Confira o exemplo:

@octocat :+1: This PR looks great - it's ready to merge! :shipit:

Alertas

Os alertas são uma extensão da sintaxe blockquote que você pode usar para enfatizar informações críticas. Confira as opções disponíveis:

> [!NOTE]  
>> Highlights information that users should take into account, even when skimming.

> [!INFO]  
>> Important information about some feature.

> [!TIP]  
>> Information that serves as an 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.

Confira os exemplos:

Exemplos de cada tipo de Alerta

Ocultar conteúdo com comentários

No GitHub, você pode ocultar o conteúdo do markdown, colocando o conteúdo em um comentário HTML.

Tabela

É possível incluir tabelas com conteúdos. Confira o modelo:

| Rank | Languages |
|----- |-----------|
| 1| Javascript|
| 2| Python |
| 3| SQL |

Template de documentação


Preencha corretamente este template para que os usuários consigam utilizar o seu conteúdo. As informações serão expostas na página do Plugin, Stack, Starter e Action no Portal da StackSpot.


# **Nome {{ Plugin/Stack/Action/Starter }}**

Escreva uma descrição clara e breve do conteúdo {{ do Plugin/Action/Stack/Starter }}.

Exemplo:
> Este Plugin contém instruções de como preencher as informações para usar os Plugins na plataforma StackSpot.

## **Pré-requisitos**

- Descreva em uma lista todos os itens e ações necessárias antes de aplicar {{ o Plugin ou criar Stack/Action/Starter }}.

Exemplo:
1. Instalar dependências;
2. Crie o arquivo de configuração;
3. Crie a pasta **template**.

## **Uso**

Descreva as etapas para o usuário utilizar {{ este Plugin/Stack/Action/Starter }}:

### Entradas

### Métodos

### Recursos

### Insira as Dependências do seu Plugin (se necessário)


Exemplo:

### Entrada

Na pasta da sua Aplicação, aplique o **plugin-doc-template** para preencher os arquivos:

1. Execute o comando:

`stk apply plugin /Users/Home/plugin-doc-template`

2. Preencha as informações do Plugin seguindo os exemplos de modelo de arquivo x;

## **Release Notes**

Esta seção só é necessária se você publicar uma nova versão de {{ Plugin/Stack/Action/Starter }}. Apenas adicione o que foi modificado ou adicionado.

Exemplo:
## **plugin-doc-template v1.0.0**

### Features
Novos templates foram adicionados.