Scrivere i contenuti

Formattazione Markdown e HTML

La maggior parte dei nostri contenuti su DevSite è scritta in Markdown, un formato di scrittura progettato per la semplicità e la leggibilità del testo normale. DevSite converte automaticamente il Markdown in HTML per la visualizzazione sul web.

Per scoprire l'equivalente Markdown specifico di Google degli elementi HTML comuni, utilizza il cheat sheet all'indirizzo go/g3mark-cheat. Puoi accedere alla documentazione completa di Markdown di Google, chiamato anche CommonMark, qui .

Ecco alcuni esempi:

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 utilizzare HTML anziché Markdown

Esistono alcuni elementi per cui non utilizziamo Markdown, tra cui:

  • Includi file: tutti i file inclusi devono essere file HTML e pertanto non devono includere elementi scritti in Markdown. Per indicazioni sulla creazione di file di inclusione, consulta Riutilizzare i contenuti in più pagine.

  • Tabelle: le tabelle Markdown possono essere difficili da formattare e gestire, quindi utilizziamo HTML per le tabelle, anche nei file Markdown.

  • Immagini: l'utilizzo di HTML per le immagini consente una maggiore flessibilità per il formato e il posizionamento delle immagini. Consulta la Guida alla pubblicazione del sito per sviluppatori per le immagini.

  • Zippies: gli Zippies, noti come widget espandibili su Devsite, devono essere in HTML e racchiusi in un tag <div>.

Formati di contenuti comuni

Segui le linee guida per i link per sapere quando aprire i link nella stessa scheda o in una nuova. Se devi aprire un link in una nuova scheda, puoi formattarlo nei seguenti modi:

Markdown

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

HTML

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

Tabelle

Per i tipi di tabelle offerti da Devsite e il relativo codice HTML, consulta la Guida alla pubblicazione di DevSite per le tabelle.

Suggerimenti:

  • Se vuoi che la tabella non abbia bordi, utilizza class="columns"

  • Se vuoi che la tabella abbia spaziatura interna e linee di divisione (come questa pagina), utilizza class="columns extra-padding" e i tag <hr> in una riga separata tra le righe di contenuti.

Sacchetti espandibili

Per Workspace, utilizziamo la classe arrow-icon per definire lo stile della sezione comprimibile. Di seguito è riportato un esempio di widget espandibile per Workspace:

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

Per utilizzare questo esempio, sostituisci le seguenti variabili:

  • UNIQUE_ZIPPY_ID: inserisci un ID descrittivo e univoco in modo da poter indirizzare direttamente lo zippy, ad esempio direct-admin-access.
  • ZIPPY_HEADING: inserisci il testo che l'utente deve visualizzare prima di espandere la sezione comprimibile.
  • YOUR_CONTENT: inserisci i contenuti che l'utente deve visualizzare quando la sezione comprimibile è espansa.

Per saperne di più sul widget espandibile di DevSite, consulta la guida alla pubblicazione di DevSite, Widget: espandibile.

Includi contenuti condivisi

Per riutilizzare i contenuti in più pagine, puoi utilizzare gli include, che sono la versione DevSite dell'utilizzo degli snippet in più articoli in Composer.

Per indicazioni sulla creazione di file inclusi e sull'utilizzo delle inclusioni nei contenuti, consulta Riutilizzare i contenuti in più pagine.

Aggiungere ancore personalizzate alle intestazioni

DevSite crea un attributo ID HTML per ogni intestazione. Per mantenere la coerenza nel caso in cui l'intestazione cambi, puoi aggiungere un ID ancora personalizzato a un'intestazione aggiungendo {:#your-id} accanto al testo dell'intestazione, ad esempio:

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

Suggerimento: per creare automaticamente ID ancora personalizzati per tutti i titoli di un file, premi Comando (⌘) + H (Ctrl + H su Windows). Gli ID ancora personalizzati esistenti non verranno modificati.

Per ulteriori informazioni, consulta la guida alla pubblicazione del sito per sviluppatori per gli ID intestazione.