Przewodnik po składni Markdown — Nagłówki, tabele, kod i więcej

To jest referencja składni Markdown, którą możesz zapisać w zakładkach i do niej wracać. Każdy element omówiony z prawdziwym przykładem — nagłówki, akcent, linki, obrazy, listy, bloki kodu, tabele, cytaty blokowe i nie tylko. Gdzie funkcja jest częścią standardowego CommonMark, jest tak oznaczona; rozszerzenia z GitHub Flavored Markdown (GFM) są wyraźnie wskazane, abyś wiedział, co jest powszechnie obsługiwane, a co zależy od renderera.

Nagłówki

Markdown ma dwa style nagłówków. Styl ATX używa znaków hash — jeden # dla h1 do sześciu ###### dla h6. Styl setext używa podkreśleń znakami = lub - i sięga tylko h1 i h2. ATX to styl, którego powinieneś używać wszędzie — jest wyraźny, skaluje się do wszystkich sześciu poziomów i jest obsługiwany przez każde narzędzie. Jeden powszechny błąd: zapominanie o spacji po #. Ściśle mówiąc, #Nagłówek nie jest nagłówkiem w CommonMark — spacja jest wymagana.

# Page Title (h1)
## Section Heading (h2)
### Subsection (h3)
#### Detail Level (h4)
##### Minor Heading (h5)
###### Smallest Heading (h6)

---

<!-- Setext style — only h1 and h2, rarely used -->
Page Title
==========

Section Heading
---------------

W prawdziwym dokumencie zazwyczaj używasz jednego h1 na górze (tytuł dokumentu), h2 dla głównych sekcji i h3 dla podsekcji w nich. Schodzenie głębiej niż h3 to sygnał, że dokument może wymagać restrukturyzacji, a nie kolejnego poziomu zagnieżdżenia.

Formatowanie tekstu

Pogrubienie używa podwójnych gwiazdek lub podwójnych podkreśleń. Kursywa używa pojedynczych gwiazdek lub pojedynczych podkreśleń. Pogrubiona kursywa łączy trzy z któregokolwiek. Przekreślenie to rozszerzenie GFM i używa podwójnych tyld. Kod wbudowany używa cudzysłowów odwróconych.

**Bold text** or __Bold text__
*Italic text* or _Italic text_
***Bold and italic*** or ___Bold and italic___
~~Strikethrough~~ (GFM only)
`inline code`

Warianty * i _ są w większości zamienne, ale różnią się w jednym przypadku brzegowym: akcent w środku słowa. Gwiazdki działają w środku słowa (un*believe*able renderuje się jako unbelieveable), ale podkreślenia nie — un_believe_able renderuje się dosłownie w CommonMark, ponieważ podkreślenia wewnątrz słów są traktowane jako znaki słowne, a nie markery akcentu. Ma to znaczenie w tekstach technicznych, gdzie podkreślenia pojawiają się w identyfikatorach. Jako zasada: używaj * dla akcentu i rezerwuj _ tylko jeśli masz silne preferencje stylistyczne. Nie mieszaj * i _ w tym samym zakresie akcentu — *text_ nie zamknie się poprawnie.

Linki i obrazy

Istnieją trzy style linków: linki wbudowane, linki referencyjne i autolinki. Obrazy mają tę samą składnię co linki wbudowane, ale z prefiksem !.

<!-- Inline link: [text](url) or [text](url "title") -->
Read the [CommonMark spec](https://spec.commonmark.org/current/ "CommonMark Specification")
Format Markdown with the [Markdown Formatter](/markdown-formatter)

<!-- Reference link: define the URL separately — cleaner in long documents -->
Check the [GFM spec][gfm] for GitHub-specific extensions.

[gfm]: https://github.github.com/gfm/

<!-- Autolink: angle brackets make a URL or email clickable -->
<https://commonmark.org>
<[email protected]>

<!-- Image: same as inline link but with ! prefix -->
![Project screenshot](./docs/screenshot.png "Dashboard view")
![Alt text for accessibility](https://example.com/logo.png)

Listy

Listy nieuporządkowane używają -, * lub + jako markery wypunktowania. Listy uporządkowane używają cyfr po których następuje kropka. Zagnieżdżaj listy przez wcięcie dwóch lub czterech spacji. Listy zadań (GFM) używają [ ] dla niezaznaczonych i [x] dla zaznaczonych elementów.

<!-- Unordered list -->
- Install dependencies
- Configure environment variables
- Run the dev server

<!-- Ordered list -->
1. Clone the repository
2. Run `npm install`
3. Copy `.env.example` to `.env` and fill in values
4. Run `npm run dev`

<!-- Nested list (indent 2 or 4 spaces) -->
- Backend
  - Set up PostgreSQL
  - Configure connection string
- Frontend
  - Install Tailwind
  - Configure PostCSS

<!-- Task list (GFM) — great for README checklists -->
## Release Checklist

- [x] Unit tests passing
- [x] End-to-end tests passing
- [ ] Changelog updated
- [ ] Docker image tagged
- [ ] Deployment approved

Kod — wbudowany i ogrodzony

Kod wbudowany używa pojedynczego cudzysłowu odwróconego po każdej stronie. W przypadku bloków użyj potrójnych cudzysłowów odwróconych (ogrodzone bloki kodu) i opcjonalnie podaj identyfikator języka zaraz po otwierającym ogrodzeniu — umożliwia to podświetlanie składni na GitHubie, w podglądach VS Code i w większości generatorów stron statycznych. Możesz również używać wcięcionych bloków kodu (4 spacje wcięcia), ale preferuj ogrodzone bloki: obsługują podpowiedzi języka, są wyraźne i działają nawet gdy otaczająca zawartość ma też wcięcia.

<!-- Inline code -->
Use the `fetch()` API to make HTTP requests.
Set the `Content-Type` header to `application/json`.

<!-- Fenced code block with language hint -->
```python
import json

with open("config.json") as f:
    config = json.load(f)

print(config["database"]["host"])
```

```typescript
interface ApiResponse<T> {
  data: T;
  status: number;
  message: string;
}

async function fetchUser(id: string): Promise<ApiResponse<User>> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}
```

```bash
# Install dependencies and start the dev server
npm install
npm run dev
```

```json
{
  "name": "my-project",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build"
  }
}
```

```yaml
name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test
```

Powszechne identyfikatory języków: python, js lub javascript, ts lub typescript, bash lub sh, json, yaml, html, css, sql, go, rust, java. Podgląd renderowania Markdown możesz zobaczyć w narzędziu Podgląd Markdown.

Tabele (GFM)

Tabele to rozszerzenie GitHub Flavored Markdown — nie są częścią standardu CommonMark. Działają na GitHubie, GitLabie, większości generatorów stron statycznych i VS Code, ale nie we wszystkich procesorach Markdown. Składnia używa znaków pionowej kreski do rozdzielania kolumn i wiersza separatora myślników do oznaczenia nagłówka. Dwukropki w wierszu separatora kontrolują wyrównanie kolumn.

| Feature              | CommonMark | GFM       |
| -------------------- | :--------: | :-------: |
| Headings             | ✅         | ✅        |
| Bold / Italic        | ✅         | ✅        |
| Fenced code blocks   | ✅         | ✅        |
| Tables               | ❌         | ✅        |
| Task lists           | ❌         | ✅        |
| Strikethrough        | ❌         | ✅        |
| Autolinks            | ✅         | ✅ (ext.) |

Wyrównanie kolumn jest ustawiane w wierszu separatora. :--- wyrównuje do lewej (domyślnie). ---: wyrównuje do prawej. :---: centruje. Nie musisz dopełniać kolumn spacjami, aby były wizualnie wyrównane w źródle — to jest kosmetyczne i nie ma żadnego wpływu na renderowane wyjście. Pionowe kreski na początku i końcu każdego wiersza są technicznie opcjonalne w GFM, ale ich używanie jest czystszym stylem.

Cytaty blokowe

Cytaty blokowe poprzedzają każdą linię znakiem >. Zagnieżdżone cytaty blokowe używają >>. Możesz umieszczać inne elementy Markdown — nagłówki, listy, bloki kodu — wewnątrz cytatu blokowego, co czyni je użytecznymi jako ramki objaśnień w dokumentacji.

> **Note:** As of Node.js 18, the `fetch` API is available globally
> without importing anything. No more `node-fetch` dependency.

> This is a quote that spans
> multiple lines.
>
> And has a second paragraph.

> Outer quote.
>
> > Nested quote — useful for "quoting a quote" in changelogs
> > or spec discussions.

<!-- Blockquote containing a code block — useful for quoting error messages -->
> The migration failed with:
>
> ```
> ERROR: relation "users" already exists
> ```

Poziome linie, podziały wierszy i escapowanie

Te trzy funkcje mylą ludzi, ponieważ ich zachowanie wygląda jak błąd, dopóki nie poznasz zasad. Poziome linie, twarde podziały wierszy i escapowanie odwrotnym ukośnikiem mają specyficzną składnię, która nie jest oczywista.

<!-- Horizontal rules: three or more of ---, ***, or ___ on their own line -->
---
***
___

<!-- All three render as <hr>. Most common style is --- -->

<!-- Hard line breaks: end a line with two trailing spaces, or use backslash -->
First line with two trailing spaces
Second line (rendered as a new line, not a new paragraph)

First line with backslash\
Second line (same result)

<!-- A single newline in Markdown source is NOT a line break — it's a space.
     Two newlines = a paragraph break. -->

<!-- Backslash escaping: put  before any Markdown character to render it literally -->
*This is not italic*
# This is not a heading
[Not a link](not-a-url)
`Not inline code`

<!-- Characters that can be escaped -->
\ ` * _ { } [ ] ( ) # + - . !

HTML w Markdown

Większość procesorów Markdown przepuszcza surowy HTML bez zmian, co odblokowuje garść przydatnych wzorców, których czysta składnia Markdown nie może wyrazić. Najczęstszym przypadkiem użycia w plikach README na GitHubie jest zwijalna sekcja <details>/<summary>. Inne przydatne: <kbd> dla skrótów klawiaturowych i niestandardowe atrybuty id na nagłówkach dla precyzyjnych kotwic.

<!-- Collapsible section — very common in GitHub READMEs -->
<details>
<summary>Click to expand: Advanced configuration options</summary>

You can override the defaults by creating a `config.local.json` file
in the project root. Supported keys:

| Key        | Default | Description             |
| ---------- | ------- | ----------------------- |
| `port`     | 3000    | Dev server port         |
| `logLevel` | `info`  | One of debug/info/warn  |

</details>

<!-- Keyboard shortcuts -->
Press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> to open the command palette.

<!-- Custom heading ID for anchor links -->
<h2 id="configuration-reference">Configuration Reference</h2>

<!-- Link to that heading from anywhere -->
See the [Configuration Reference](#configuration-reference).

Jedno ważne zastrzeżenie: blok <details> wymaga pustej linii między zamykającym tagiem </summary> a treścią, jeśli ta treść zawiera Markdown. Bez pustej linii Markdown wewnątrz nie zostanie sparsowany — będzie renderowany jako zwykły tekst. Możesz czyścić i formatować pliki Markdown za pomocą narzędzia Formater Markdown.

Podsumowanie

To obejmuje pełną składnię — standardowy CommonMark i rozszerzenia GFM, których programiści używają codziennie. Dla autorytatywnego słowa w kwestii przypadków brzegowych specyfikacja CommonMark i specyfikacja GFM to oba czytelne dokumenty, nie tylko zrzuty referencyjne. Szybka referencja CommonMark to poręczne jednostronicowe podsumowanie. Strony podstawowej składni Markdown Guide i rozszerzonej składni są też dobrze zorganizowane, jeśli chcesz więcej wyjaśnień prozą obok przykładów. Gdy potrzebujesz zobaczyć, jak dokładnie wygląda Twój Markdown przed zatwierdzeniem, narzędzie Podgląd Markdown renderuje go na żywo w przeglądarce. Aby wyczyścić niespójne formatowanie w dokumencie, Formater Markdown normalizuje style nagłówków, markery list i odstępy. A dla produkcji czystego HTML z wyjścia Markdown, Formater HTML upiększa wszystko, co emituje procesor Markdown.