Napisz treść

Formatowanie Markdown i HTML

Większość treści w DevSite jest napisana w formacie Markdown, który jest formatem pisania zaprojektowanym z myślą o prostocie i czytelności w zwykłym tekście. DevSite automatycznie konwertuje Markdown na HTML, aby wyświetlać go w internecie.

Aby poznać odpowiedniki w Markdownie Google popularnych elementów HTML, skorzystaj z arkusza w go/g3mark-cheat. Pełną dokumentację formatu Markdown od Google, zwanego też CommonMark, znajdziesz tutaj.

Oto kilka przykładów:

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

Kiedy używać HTML zamiast Markdown

Nie używamy Markdowna w przypadku niektórych elementów, takich jak:

  • Pliki dołączane: wszystkie pliki dołączane powinny być plikami HTML, a więc nie powinny zawierać żadnych elementów zapisanych w Markdownie. Wskazówki dotyczące tworzenia plików dołączanych znajdziesz w artykule Ponowne wykorzystywanie treści na różnych stronach.

  • Tabele: formatowanie i utrzymywanie tabel w Markdown może być trudne, dlatego używamy HTML w przypadku tabel, nawet w plikach Markdown.

  • Grafika: używanie HTML w przypadku obrazów zapewnia większą elastyczność w zakresie formatu i umieszczania obrazów. Więcej informacji znajdziesz w przewodniku publikowania w DevSite dotyczącym obrazów.

  • Zippies: Zippies, czyli rozwijane widżety w Devsite, muszą być w formacie HTML i zawierać tag <div>.

Typowe formaty treści

Postępuj zgodnie z wytycznymi dotyczącymi linków, aby wiedzieć, kiedy otwierać linki w tej samej karcie, a kiedy w nowej. Jeśli chcesz otworzyć link w nowej karcie, możesz sformatować go w jeden z tych sposobów:

Markdown

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

HTML

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

Tabele

Informacje o typach tabel dostępnych w Devsite i odpowiadającym im kodzie HTML znajdziesz w przewodniku po publikowaniu w Devsite w sekcji Tabele.

Wskazówki:

  • Jeśli chcesz, aby tabela nie miała obramowania, użyj class="columns"

  • Jeśli chcesz, aby tabela zawierała dopełnienie i linie podziału (jak na tej stronie), użyj tagu class="columns extra-padding", a tagów <hr> w osobnym wierszu między wierszami treści.

Rozwijane segmenty

W Workspace używamy klasy arrow-icon do stylizowania zippy. Poniżej znajdziesz przykład rozwijanego widżetu w Workspace:

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

Aby użyć tego przykładu, zastąp te zmienne:

  • UNIQUE_ZIPPY_ID: Wpisz opisowy i unikalny identyfikator, aby móc bezpośrednio odwoływać się do pliku zippy, np. direct-admin-access.
  • ZIPPY_HEADING: wpisz tekst, który użytkownik powinien zobaczyć przed rozwinięciem elementu zippy.
  • YOUR_CONTENT: wpisz treść, która ma się wyświetlać użytkownikowi po rozwinięciu elementu zippy.

Więcej informacji o rozwijanym widżecie DevSite znajdziesz w przewodniku DevSite Publishing w sekcji Widżety: rozwijane.

Uwzględnianie udostępnionych treści

Aby ponownie wykorzystać treści na wielu stronach, możesz użyć funkcji includes, która jest wersją DevSite funkcji używania fragmentów kodu w wielu artykułach w Composerze.

Więcej informacji o tworzeniu plików dołączanych i używaniu ich w treściach znajdziesz w artykule Ponowne wykorzystywanie treści na różnych stronach.

Dodawanie niestandardowych kotwic do nagłówków

DevSite tworzy atrybut identyfikatora HTML dla każdego nagłówka. Aby zachować spójność w przypadku zmiany nagłówka, możesz dodać do niego niestandardowy identyfikator kotwicy, umieszczając znak {:#your-id} obok tekstu nagłówka, np.:

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

Wskazówka: aby automatycznie utworzyć niestandardowe identyfikatory kotwic dla wszystkich nagłówków w pliku, naciśnij Command (⌘) + H (Ctrl + H w systemie Windows). Istniejące niestandardowe identyfikatory punktów kotwiczących nie zostaną zmienione.

Więcej informacji znajdziesz w przewodniku po publikowaniu w DevSite dotyczącym identyfikatorów nagłówków.