Documentar conteúdo
Nesta seção, você encontra as regras de escrita de Markdown para criar a sua documentação de conteúdo.
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.
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
Estilo | Sintaxe | Exemplo | Saída |
---|---|---|---|
Negrito | ** ** ou __ __ | This is bold text | This is bold text |
Itálico | * * ou _ _ | _ This text is italicized _ | This text is italicized |
Tachado | ~~ ~~ | ~~ This was mistaken text ~~ | |
Negrito e itálico alinhado | ** ** e _ _ | This text is _ extremely _ important | This text is extremely important |
Todo em negrito e itálico | ******* ******* | All this text is important | All this text is important |
Subscrito | < sub > < /sub > | This is a < sub >subscript< /sub > text | This is a subscript text |
Sobrescrito | < sup > < /sup > | This is a < sup >superscript< /sup > text | This 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/>
Links
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/).
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:
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:
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.