Escrever seu conteúdo

Formatação em Markdown e HTML

A maior parte do conteúdo do DevSite é escrita em Markdown, um formato de escrita projetado para simplicidade e legibilidade humana em texto simples. O DevSite converte automaticamente o Markdown em HTML para exibição na Web.

Para saber o equivalente em Markdown específico do Google dos elementos HTML comuns, use a tabela de referência em go/g3mark-cheat. Acesse a documentação completa do Markdown do Google, também chamado de CommonMark, neste link.

Veja alguns exemplos:

HTML Markdown
<b>bold text</b>
<strong>bold text</strong>		 **bold text**
<i>italic text</i>
<em>italic text</em>		 *italic text*
<h2>Heading 2</h2>
<h3>Heading 3</h3>		 ## Heading 2
### Heading 3
<a href="url.com">Link</a> [Link](url.com)
<p>paragraph</p> Paragraph
<ol>
  <li>Ordered list first item</li>
  <li>Second item</li>
</ol>		 1. Ordered list first item
1. Second item
1. Third item
<ul>
<li>Unordered list first item</li>
  <ul>
    <li>Nested list item</li>
  </ul>
<li>Second item</li>
</ul>		 * Unordered list first item
    * Nested item (indent 4-spaces)
* Second item

Quando usar HTML em vez de Markdown

Há alguns itens que não usamos o Markdown para escrever, incluindo:

  • Incluir arquivos: todos os arquivos incluídos precisam ser HTML e, portanto, não podem ter elementos escritos em Markdown. Para orientações sobre como criar arquivos de inclusão, consulte Reutilizar conteúdo em várias páginas.

  • Tabelas: as tabelas Markdown podem ser difíceis de formatar e manter. Por isso, usamos HTML para tabelas, mesmo em arquivos Markdown.

  • Imagens: o uso de HTML para imagens permite mais flexibilidade no formato e no posicionamento delas. Consulte o guia de publicação do DevSite para Imagens.

  • Zippies: os zippies, conhecidos como widgets expansíveis no Devsite, precisam estar em HTML e envolvidos em uma tag <div>.

Formatos de conteúdo comuns

Siga as diretrizes de links para saber quando abrir links na mesma guia ou em uma nova. Se você precisar abrir um link em uma nova guia, formate-o das seguintes maneiras:

Markdown

[Accessible content](/style/accessibility){:target="_blank"}

HTML

<a href="/style/accessibility" target="_blank">Accessible content</a>

Tabelas

Para saber mais sobre os tipos de tabelas oferecidas pelo DevSite e o HTML correspondente, consulte o guia de publicação do DevSite para Tabelas.

Dicas:

  • Se você não quiser bordas na tabela, use class="columns".

  • Se você quiser que a tabela tenha padding e linhas divisórias (como esta página), use class="columns extra-padding" e tags <hr> em uma linha separada entre as linhas de conteúdo.

Seções expansíveis

No Workspace, usamos a classe arrow-icon para estilizar o zippy. Confira um exemplo de widget expansível para o Workspace:

<div>
  <devsite-expandable class="arrow-icon" id="UNIQUE_ZIPPY_ID">
    <h4 class="showalways">ZIPPY_HEADING</h4>
    <div>
      YOUR_CONTENT
    </div>
  </devsite-expandable>
</div>

Para usar este exemplo, substitua as seguintes variáveis:

  • UNIQUE_ZIPPY_ID: insira um ID descritivo e exclusivo para que você possa apontar diretamente para o zippy, por exemplo, direct-admin-access.
  • ZIPPY_HEADING: insira o texto que o usuário vai ver antes de expandir o zippy.
  • YOUR_CONTENT: insira o conteúdo que o usuário vai ver quando o zippy for aberto.

Para mais informações sobre o widget expansível do DevSite, consulte o guia de publicação do DevSite, Widgets: expansíveis.

Incluir conteúdo compartilhado

Para reutilizar conteúdo em várias páginas, use includes, que é a versão do DevSite para usar snippets em vários artigos no Composer.

Para orientações sobre como criar arquivos de inclusão e usar inclusões no seu conteúdo, consulte Reutilizar conteúdo em várias páginas.

Adicionar âncoras personalizadas aos cabeçalhos

O DevSite cria um atributo ID HTML para cada cabeçalho. Para manter a consistência caso o cabeçalho mude, adicione um ID de âncora personalizado a um cabeçalho adicionando {:#your-id} ao lado do texto do cabeçalho. Por exemplo:

## Apply filters to your search results {:#apply-filters}

Dica: para criar automaticamente IDs de âncora personalizados para todos os cabeçalhos em um arquivo, pressione Command (\⌘) + H (Ctrl + H no Windows). Os IDs de âncora personalizados atuais não serão alterados.

Para mais informações, consulte o guia de publicação do DevSite para IDs de cabeçalho.