Adnotări

Adnotările sunt micile marcaje autorizate care transformă un MDX simplu în conținut structurat pentru site. Ele definesc subpaginile proiectelor, slug-uri stabile, rezumate, fișiere puse în prim-plan și detalii de prezentare a codului, fără a muta aceste informații în codul rutelor.

Această pagină adună elementele de bază utile atât la scrierea manuală, cât și la solicitarea agenților să producă conținut. Fiecare secțiune arată mai întâi tiparul sursă, apoi explică ce face pagina redată cu el.

Încadrare și valori implicite pentru bloc

Adnotările de prezentare la nivel de bloc controlează cromatica implicită, indicatorii de linie, anteturile și controalele de suprapunere fără a necesita o componentă personalizată în fișierul MDX.

Eticheta limbajului

Blocurile de cod își arată limbajul curent ca etichetă, în mod implicit. Nu schimbă și nu modifică codul. Folosește !no-language pentru a o ascunde, sau !language pentru a o activa explicit.

1
export const packageManagers = ['yarn', 'pnpm', 'npm'];

1
// !language
2
export const packageManagers = ['yarn', 'pnpm', 'npm'];

1
// !no-language
2
export const packageManagers = ['yarn', 'pnpm', 'npm'];

Numerotarea liniilor

Codul care nu este de tip shell afișează numerotarea liniilor în mod implicit. Blocurile de shell o omit, astfel încât comenzile scurte să rămână compacte, dar !line-numbers reactivează opțiunea pentru un exemplu individual de shell. Folosește !no-line-numbers pentru a dezactiva valoarea implicită pentru orice limbaj.

1
const managers = [
2
  'yarn',
3
  'pnpm',
4
  'npm',
5
];

1
// !line-numbers
2
const managers = [
3
  'yarn',
4
  'pnpm',
5
  'npm',
6
];

// !no-line-numbers
const managers = [
  'yarn',
  'pnpm',
  'npm',
];

1
# !line-numbers
2
# !no-shell-prompt
3
function website_build() {
4
  local project=${1:-website}
5

6
  if [[ $project == website ]]; then
7
    yarn install --immutable
8
    yarn moon run "$project:build"
9
  else
10
    print "Unknown project: $project" >&2
11
    return 1
12
  fi
13
}

Butonul de copiere

Blocurile de shell arată un buton de copiere în mod implicit, în timp ce blocurile care nu sunt de tip shell păstrează butoanele de copiere opționale. Folosește !copy pentru a activa copierea, sau !no-copy pentru a o ascunde.

1
// !copy
2
export const packageManagers = ['yarn', 'pnpm', 'npm'];

Când !copy este prezent alături de eticheta limbajului, ambele împart aceeași bară de suprapunere.

Prefixul de shell

Proiectul rulează prin sarcinile Yarn și Moon ale repository-ului. Blocurile de shell arată prefixul $ și un buton de copiere în mod implicit. Folosește !no-shell-prompt sau !no-copy atunci când un bloc de shell nu trebuie să arate unul dintre acestea, sau folosește !shell-prompt și !copy pentru a le adăuga la un alt limbaj de cod.

yarn moon run website:build

# !no-shell-prompt
yarn moon run website:build

# !no-copy
yarn moon run website:build

# !no-copy
# !no-shell-prompt
yarn moon run website:build

Nume de fișier

Metadatele simple ale unei fenced code block sunt redate ca nume de fișier deasupra blocului de cod.

1
```ts package-manager.ts
2
export const packageManagers = ['yarn', 'pnpm', 'npm'];
3
```

Adnotări vizuale și de linie

Adnotările pot atrage atenția asupra unei părți specifice dintr-un exemplu sau pot ajusta prezentarea liniilor fără a schimba codul pe care cititorii îl pot copia.

Cod marcat

!mark evidențiază linia următoare. Adaugă un interval sau o expresie regulată pentru a marca doar o parte a unei linii, și adaugă o culoare după selector pentru a suprascrie accentul temei.

1
function publish(version: string) {
2
  // !mark blue
3
  assertCleanWorkingTree();
4
  // !mark[/version/] gold
5
  return createRelease(version);
6
}

Diferențe (Diffs)

!diff + și !diff - identifică liniile adăugate și eliminate. Stilizarea diferențelor reutilizează adnotarea de marcaj, astfel încât ambele funcționalități păstrează aceeași structură vizuală.

Folosește !noop înaintea unui marcator de adnotare pentru a arăta acel marcator ca și cod, în loc de a fi interpretat. Prefixul noop este omis din linia redată.

1
export function packageCommand(manager: string) {
2
  // !diff -
-
3
  return `${manager} install`;
4
  // !diff +
+
5
  return manager === 'npm' ? 'npm install' : `${manager} add`;
6
}

Detalii pliate

!fold înlocuiește conținutul inline corespunzător cu o elipsă extensibilă. Elementul disclosure nativ păstrează textul integral în documentul redat pe server și rămâne extensibil fără JavaScript.

1
// !fold[/className="(.*?)"/gm]
2
export function Status() {
3
  return <span className="...status status--ready">Ready</span>;
4
}

Încadrarea automată a textului

!word-wrap păstrează liniile lungi în interiorul lățimii disponibile și aliniază textul încadrat cu indentarea originală.

1
// !word-wrap
2
const command = createPackageManagerCommand({ manager: 'yarn', operation: 'exec', package: 'typescript', executable: 'tsc', arguments: ['--watch', '--preserveWatchOutput'] });

Componente complexe

Unele tipare de autorizare necesită mai mult decât un singur element markdown. Aceste componente păstrează sursa MDX lizibilă, permițând în același timp paginii redate să grupeze exemple, controale sau comparații înrudite într-un singur bloc.

File pentru cod (Code Tabs)

Blocurile de cod înrudite care descriu o singură schimbare în mai multe fișiere aparțin împreună, nu stivuite unul după altul.

1
<CodeWithTabs>
2

3
```ts !!tabs component.tsx
4
export function Example() {
5
  return <p>Example</p>;
6
}
7
```
8

9
```ts !!tabs component.css.ts
10
export const exampleStyle = style({
11
  display: 'block',
12
});
13
```
14

15
</CodeWithTabs>

1
export function Example() {
2
  return <p>Example</p>;
3
}

1
export const exampleStyle = style({
2
  display: 'block',
3
});

Comenzi pentru managerul de pachete

Adnotarea !package descrie o comandă neutră față de managerul de pachete și redă formele corespunzătoare pentru Yarn, pnpm și npm ca file.

Instalarea pachetelor

yarn add typescript zod

pnpm add typescript zod

npm install typescript zod

```sh !package install typescript zod
```

Fiecare variantă adaugă aceleași două pachete în proiectul curent și transmite numele lor neschimbate. Doar comanda diferă: Yarn și pnpm disting adăugarea unei dependințe de instalarea proiectului, folosind deci add, în timp ce npm suprasolicită install.

Inițierea unui proiect cu un pachet folosit o singură dată

yarn dlx create-vite my-app --template react-ts

pnpm dlx create-vite my-app --template react-ts

npx create-vite my-app --template react-ts

```sh !package exec create-vite my-app --template react-ts
```

Aici binarul și pachetul au același nume, deci nu trebuie declarat niciun pachet. Numele proiectului și argumentele șablonului sunt identice peste tot, și doar executorul se schimbă: yarn dlx, pnpm dlx și npx.

Rularea unui binar dintr-un pachet numit

yarn dlx -p typescript tsc --watch

pnpm dlx --package typescript tsc --watch

npx --package typescript tsc --watch

```sh !package exec --package typescript tsc --watch
```

Când binarul nu corespunde pachetului care îl furnizează, pachetul trebuie numit explicit. Executorii diferă la fel ca mai sus, la fel și opțiunea: Yarn o scrie -p, în timp ce pnpm și npm folosesc ambele --package.