diff options
| author | HiDeoo | 2024-09-18 10:20:48 +0200 |
|---|---|---|
| committer | GitHub | 2024-09-18 10:20:48 +0200 |
| commit | 41ed4faf1c3c01b7fcbc664549a967997d30e697 (patch) | |
| tree | 8b7a374ce3bae4e9888acb73325085d4ad6ffcb6 | |
| parent | 8112d8a29ead9c56640a6918c7bfaa5b26c74b17 (diff) | |
| download | IT.starlight-41ed4faf1c3c01b7fcbc664549a967997d30e697.tar.gz IT.starlight-41ed4faf1c3c01b7fcbc664549a967997d30e697.tar.bz2 IT.starlight-41ed4faf1c3c01b7fcbc664549a967997d30e697.zip | |
Components documentation improvements (#2121)
Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com>
Co-authored-by: Yan <61414485+yanthomasdev@users.noreply.github.com>
Co-authored-by: Lorenzo Lewis <lorenzo_lewis@icloud.com>
Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca>
@lunaria-ignore:src/content/docs/pt-pt/getting-started.mdx;src/content/docs/uk/getting-started.mdx;src/content/docs/es/getting-started.mdx;src/content/docs/fr/getting-started.mdx;src/content/docs/hi/getting-started.mdx;src/content/docs/id/getting-started.mdx;src/content/docs/it/getting-started.mdx;src/content/docs/ja/getting-started.mdx;src/content/docs/ko/getting-started.mdx;src/content/docs/pt-br/getting-started.mdx;src/content/docs/ru/getting-started.mdx;src/content/docs/tr/getting-started.mdx;src/content/docs/zh-cn/getting-started.mdx
67 files changed, 5164 insertions, 5721 deletions
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 08eb61e6..8ebde7f9 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -1,6 +1,7 @@ import { defineConfig } from 'astro/config'; import starlight from '@astrojs/starlight'; import starlightLinksValidator from 'starlight-links-validator'; +import markdocGrammar from './grammars/markdoc.tmLanguage.json'; export const locales = { root: { label: 'English', lang: 'en' }, @@ -131,6 +132,13 @@ export default defineConfig({ autogenerate: { directory: 'guides' }, }, { + label: 'Components', + translations: { + fr: 'Composants', + }, + autogenerate: { directory: 'components' }, + }, + { label: 'Reference', translations: { de: 'Referenz', @@ -162,6 +170,7 @@ export default defineConfig({ autogenerate: { directory: 'resources' }, }, ], + expressiveCode: { shiki: { langs: [markdocGrammar] } }, plugins: process.env.CHECK_LINKS ? [ starlightLinksValidator({ diff --git a/docs/grammars/README.md b/docs/grammars/README.md new file mode 100644 index 00000000..8a74cb94 --- /dev/null +++ b/docs/grammars/README.md @@ -0,0 +1,34 @@ +# Starlight Docs Grammars + +This directory contains additional grammars for the Starlight documentation website. + +## Grammars + +The following additional grammars are generated and available for use: + +- [Markdoc](https://github.com/markdoc/language-server) + +## Usage + +To generate the grammars from their source files, run: + +```sh +pnpm grammars +``` + +To include the grammars in the Starlight documentation website, update the `expressiveCode.shiki.langs` array in the `astro.config.mjs` file: + +```diff +starlight({ + expressiveCode: { + shiki: { + langs: [ + JSON.parse( + fs.readFileSync('./grammars/existing.tmLanguage.json', 'utf-8'), ++ fs.readFileSync('./grammars/new.tmLanguage.json', 'utf-8'), + ), + ], + }, + }, +}); +``` diff --git a/docs/grammars/generate.mjs b/docs/grammars/generate.mjs new file mode 100644 index 00000000..aee8d709 --- /dev/null +++ b/docs/grammars/generate.mjs @@ -0,0 +1,74 @@ +// @ts-check + +import fs from 'node:fs/promises'; + +const markdown = { + repo: 'shikijs/textmate-grammars-themes', + tmLanguagePath: 'packages/tm-grammars/grammars/markdown.json', +}; + +const markdoc = { + repo: 'markdoc/language-server', + // We don't need the Markdoc grammar, only the Markdoc Markdown grammar. + // tmLanguagePath: 'syntaxes/markdoc.tmLanguage.json', + markdownTmLanguagePath: 'syntaxes/markdoc.markdown.tmLanguage.json', +}; + +/** + * Download a TextMate grammar file from a GitHub repository. + * @param {string} repo + * @param {string} path + */ +async function fetchTmLanguage(repo, path) { + const url = `https://raw.githubusercontent.com/${repo}/main/${path}`; + const response = await fetch(url); + const data = await response.json(); + return data; +} + +// Download the TextMate grammar files for Markdown. +const markdownTmLanguage = await fetchTmLanguage(markdown.repo, markdown.tmLanguagePath); + +// Download the TextMate grammar files for Markdoc Markdown. +const markdocMarkdownTmLanguage = await fetchTmLanguage( + markdoc.repo, + markdoc.markdownTmLanguagePath +); + +// Reference: https://macromates.com/manual/en/language_grammars + +// Update the name and scope name for the Markdoc grammar. +markdownTmLanguage.name = 'markdoc'; +markdownTmLanguage.scopeName = 'text.html.markdoc'; + +// Merge the Markdown and Markdoc Markdown grammar repositories. +markdownTmLanguage.repository = { + ...markdownTmLanguage.repository, + ...markdocMarkdownTmLanguage.repository, +}; + +// Include the Markdoc Markdown grammar rules at the beginning of the Markdown grammar. +for (const rule of Object.keys(markdocMarkdownTmLanguage.repository)) { + // Skip shortcut rules as they break syntax highlighting of child content that includes dots in + // words and we don't ever use them. + if (rule === 'shortcut') continue; + + markdownTmLanguage.repository.block.patterns.unshift({ include: `#${rule}` }); + markdownTmLanguage.repository.inline.patterns.unshift({ include: `#${rule}` }); +} + +// Write the grammar to a file. +await fs.writeFile( + './grammars/markdoc.tmLanguage.json', + JSON.stringify( + markdownTmLanguage, + (key, value) => { + // The `applyEndPatternLast` property should be a boolean and not a number. + if (key === 'applyEndPatternLast') return Boolean(value); + return value; + }, + 2 + ) +); + +console.log('Markdoc grammar generated successfully.'); diff --git a/docs/grammars/markdoc.tmLanguage.json b/docs/grammars/markdoc.tmLanguage.json new file mode 100644 index 00000000..3c6ed3b8 --- /dev/null +++ b/docs/grammars/markdoc.tmLanguage.json @@ -0,0 +1,3142 @@ +{ + "displayName": "Markdown", + "name": "markdoc", + "patterns": [ + { + "include": "#frontMatter" + }, + { + "include": "#block" + } + ], + "repository": { + "ampersand": { + "comment": "Markdown will convert this for us. We match it so that the HTML grammar will not mark it up as invalid.", + "match": "&(?!([a-zA-Z0-9]+|#\\d+|#x[0-9a-fA-F]+);)", + "name": "meta.other.valid-ampersand.markdown" + }, + "block": { + "patterns": [ + { + "include": "#tag" + }, + { + "include": "#attribute" + }, + { + "include": "#separator" + }, + { + "include": "#heading" + }, + { + "include": "#blockquote" + }, + { + "include": "#lists" + }, + { + "include": "#fenced_code_block" + }, + { + "include": "#raw_block" + }, + { + "include": "#link-def" + }, + { + "include": "#html" + }, + { + "include": "#table" + }, + { + "include": "#paragraph" + } + ] + }, + "blockquote": { + "begin": "(^|\\G)[ ]{0,3}(>) ?", + "captures": { + "2": { + "name": "punctuation.definition.quote.begin.markdown" + } + }, + "name": "markup.quote.markdown", + "patterns": [ + { + "include": "#block" + } + ], + "while": "(^|\\G)\\s*(>) ?" + }, + "bold": { + "begin": "(?<open>(\\*\\*(?=\\w)|(?<!\\w)\\*\\*|(?<!\\w)\\b__))(?=\\S)(?=(<[^>]*+>|(?<raw>`+)([^`]|(?!(?<!`)\\k<raw>(?!`))`)*+\\k<raw>|\\\\[\\\\`*_{}\\[\\]()#.!+\\->]?+|\\[((?<square>[^\\[\\]\\\\]|\\\\.|\\[\\g<square>*+\\])*+\\](([ ]?\\[[^\\]]*+\\])|(\\([ \\t]*+<?(.*?)>?[ \\t]*+((?<title>['\"])(.*?)\\k<title>)?\\))))|(?!(?<=\\S)\\k<open>).)++(?<=\\S)(?=__\\b|\\*\\*)\\k<open>)", + "captures": { + "1": { + "name": "punctuation.definition.bold.markdown" + } + }, + "end": "(?<=\\S)(\\1)", + "name": "markup.bold.markdown", + "patterns": [ + { + "applyEndPatternLast": true, + "begin": "(?=<[^>]*?>)", + "end": "(?<=>)", + "patterns": [ + { + "include": "text.html.derivative" + } + ] + }, + { + "include": "#escape" + }, + { + "include": "#ampersand" + }, + { + "include": "#bracket" + }, + { + "include": "#raw" + }, + { + "include": "#bold" + }, + { + "include": "#italic" + }, + { + "include": "#image-inline" + }, + { + "include": "#link-inline" + }, + { + "include": "#link-inet" + }, + { + "include": "#link-email" + }, + { + "include": "#image-ref" + }, + { + "include": "#link-ref-literal" + }, + { + "include": "#link-ref" + }, + { + "include": "#link-ref-shortcut" + }, + { + "include": "#strikethrough" + } + ] + }, + "bracket": { + "comment": "Markdown will convert this for us. We match it so that the HTML grammar will not mark it up as invalid.", + "match": "<(?![a-zA-Z/?$!])", + "name": "meta.other.valid-bracket.markdown" + }, + "escape": { + "match": "\\\\[-`*_#+.!(){}\\[\\]\\\\>]", + "name": "constant.character.escape.markdown" + }, + "fenced_code_block": { + "patterns": [ + { + "include": "#fenced_code_block_css" + }, + { + "include": "#fenced_code_block_basic" + }, + { + "include": "#fenced_code_block_ini" + }, + { + "include": "#fenced_code_block_java" + }, + { + "include": "#fenced_code_block_lua" + }, + { + "include": "#fenced_code_block_makefile" + }, + { + "include": "#fenced_code_block_perl" + }, + { + "include": "#fenced_code_block_r" + }, + { + "include": "#fenced_code_block_ruby" + }, + { + "include": "#fenced_code_block_php" + }, + { + "include": "#fenced_code_block_sql" + }, + { + "include": "#fenced_code_block_vs_net" + }, + { + "include": "#fenced_code_block_xml" + }, + { + "include": "#fenced_code_block_xsl" + }, + { + "include": "#fenced_code_block_yaml" + }, + { + "include": "#fenced_code_block_dosbatch" + }, + { + "include": "#fenced_code_block_clojure" + }, + { + "include": "#fenced_code_block_coffee" + }, + { + "include": "#fenced_code_block_c" + }, + { + "include": "#fenced_code_block_cpp" + }, + { + "include": "#fenced_code_block_diff" + }, + { + "include": "#fenced_code_block_dockerfile" + }, + { + "include": "#fenced_code_block_git_commit" + }, + { + "include": "#fenced_code_block_git_rebase" + }, + { + "include": "#fenced_code_block_go" + }, + { + "include": "#fenced_code_block_groovy" + }, + { + "include": "#fenced_code_block_pug" + }, + { + "include": "#fenced_code_block_js" + }, + { + "include": "#fenced_code_block_js_regexp" + }, + { + "include": "#fenced_code_block_json" + }, + { + "include": "#fenced_code_block_jsonc" + }, + { + "include": "#fenced_code_block_less" + }, + { + "include": "#fenced_code_block_objc" + }, + { + "include": "#fenced_code_block_swift" + }, + { + "include": "#fenced_code_block_scss" + }, + { + "include": "#fenced_code_block_perl6" + }, + { + "include": "#fenced_code_block_powershell" + }, + { + "include": "#fenced_code_block_python" + }, + { + "include": "#fenced_code_block_julia" + }, + { + "include": "#fenced_code_block_regexp_python" + }, + { + "include": "#fenced_code_block_rust" + }, + { + "include": "#fenced_code_block_scala" + }, + { + "include": "#fenced_code_block_shell" + }, + { + "include": "#fenced_code_block_ts" + }, + { + "include": "#fenced_code_block_tsx" + }, + { + "include": "#fenced_code_block_csharp" + }, + { + "include": "#fenced_code_block_fsharp" + }, + { + "include": "#fenced_code_block_dart" + }, + { + "include": "#fenced_code_block_handlebars" + }, + { + "include": "#fenced_code_block_markdown" + }, + { + "include": "#fenced_code_block_log" + }, + { + "include": "#fenced_code_block_erlang" + }, + { + "include": "#fenced_code_block_elixir" + }, + { + "include": "#fenced_code_block_latex" + }, + { + "include": "#fenced_code_block_bibtex" + }, + { + "include": "#fenced_code_block_twig" + }, + { + "include": "#fenced_code_block_unknown" + } + ] + }, + "fenced_code_block_basic": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(html|htm|shtml|xhtml|inc|tmpl|tpl)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.html", + "patterns": [ + { + "include": "text.html.basic" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_bibtex": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(bibtex)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.bibtex", + "patterns": [ + { + "include": "text.bibtex" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_c": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(c|h)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.c", + "patterns": [ + { + "include": "source.c" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_clojure": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(clj|cljs|clojure)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.clojure", + "patterns": [ + { + "include": "source.clojure" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_coffee": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(coffee|Cakefile|coffee.erb)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.coffee", + "patterns": [ + { + "include": "source.coffee" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_cpp": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(cpp|c\\+\\+|cxx)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.cpp source.cpp", + "patterns": [ + { + "include": "source.cpp" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_csharp": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(cs|csharp|c#)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.csharp", + "patterns": [ + { + "include": "source.cs" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_css": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(css|css.erb)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.css", + "patterns": [ + { + "include": "source.css" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_dart": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(dart)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.dart", + "patterns": [ + { + "include": "source.dart" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_diff": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(patch|diff|rej)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.diff", + "patterns": [ + { + "include": "source.diff" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_dockerfile": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(dockerfile|Dockerfile)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.dockerfile", + "patterns": [ + { + "include": "source.dockerfile" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_dosbatch": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(bat|batch)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.dosbatch", + "patterns": [ + { + "include": "source.batchfile" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_elixir": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(elixir)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.elixir", + "patterns": [ + { + "include": "source.elixir" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_erlang": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(erlang)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.erlang", + "patterns": [ + { + "include": "source.erlang" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_fsharp": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(fs|fsharp|f#)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.fsharp", + "patterns": [ + { + "include": "source.fsharp" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_git_commit": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(COMMIT_EDITMSG|MERGE_MSG)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.git_commit", + "patterns": [ + { + "include": "text.git-commit" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_git_rebase": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(git-rebase-todo)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.git_rebase", + "patterns": [ + { + "include": "text.git-rebase" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_go": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(go|golang)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.go", + "patterns": [ + { + "include": "source.go" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_groovy": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(groovy|gvy)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.groovy", + "patterns": [ + { + "include": "source.groovy" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_handlebars": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(handlebars|hbs)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.handlebars", + "patterns": [ + { + "include": "text.html.handlebars" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_ini": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(ini|conf)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.ini", + "patterns": [ + { + "include": "source.ini" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_java": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(java|bsh)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.java", + "patterns": [ + { + "include": "source.java" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_js": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(js|jsx|javascript|es6|mjs|cjs|dataviewjs|\\{\\.js.+?\\})((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.javascript", + "patterns": [ + { + "include": "source.js" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_js_regexp": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(regexp)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.js_regexp", + "patterns": [ + { + "include": "source.js.regexp" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_json": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(json|json5|sublime-settings|sublime-menu|sublime-keymap|sublime-mousemap|sublime-theme|sublime-build|sublime-project|sublime-completions)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.json", + "patterns": [ + { + "include": "source.json" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_jsonc": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(jsonc)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.jsonc", + "patterns": [ + { + "include": "source.json.comments" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_julia": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(julia|\\{\\.julia.+?\\})((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.julia", + "patterns": [ + { + "include": "source.julia" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_latex": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(latex|tex)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.latex", + "patterns": [ + { + "include": "text.tex.latex" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_less": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(less)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.less", + "patterns": [ + { + "include": "source.css.less" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_log": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(log)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.log", + "patterns": [ + { + "include": "text.log" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_lua": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(lua)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.lua", + "patterns": [ + { + "include": "source.lua" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_makefile": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(Makefile|makefile|GNUmakefile|OCamlMakefile)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.makefile", + "patterns": [ + { + "include": "source.makefile" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_markdown": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(markdown|md)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.markdown", + "patterns": [ + { + "include": "text.html.markdown" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_objc": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(objectivec|objective-c|mm|objc|obj-c|m|h)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.objc", + "patterns": [ + { + "include": "source.objc" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_perl": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(perl|pl|pm|pod|t|PL|psgi|vcl)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.perl", + "patterns": [ + { + "include": "source.perl" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_perl6": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(perl6|p6|pl6|pm6|nqp)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.perl6", + "patterns": [ + { + "include": "source.perl.6" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_php": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(php|php3|php4|php5|phpt|phtml|aw|ctp)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.php", + "patterns": [ + { + "include": "text.html.basic" + }, + { + "include": "source.php" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_powershell": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(powershell|ps1|psm1|psd1|pwsh)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.powershell", + "patterns": [ + { + "include": "source.powershell" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_pug": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(jade|pug)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.pug", + "patterns": [ + { + "include": "text.pug" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_python": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(python|py|py3|rpy|pyw|cpy|SConstruct|Sconstruct|sconstruct|SConscript|gyp|gypi|\\{\\.python.+?\\})((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.python", + "patterns": [ + { + "include": "source.python" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_r": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(R|r|s|S|Rprofile|\\{\\.r.+?\\})((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.r", + "patterns": [ + { + "include": "source.r" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_regexp_python": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(re)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.regexp_python", + "patterns": [ + { + "include": "source.regexp.python" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_ruby": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(ruby|rb|rbx|rjs|Rakefile|rake|cgi|fcgi|gemspec|irbrc|Capfile|ru|prawn|Cheffile|Gemfile|Guardfile|Hobofile|Vagrantfile|Appraisals|Rantfile|Berksfile|Berksfile.lock|Thorfile|Puppetfile)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.ruby", + "patterns": [ + { + "include": "source.ruby" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_rust": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(rust|rs|\\{\\.rust.+?\\})((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.rust", + "patterns": [ + { + "include": "source.rust" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_scala": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(scala|sbt)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.scala", + "patterns": [ + { + "include": "source.scala" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_scss": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(scss)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.scss", + "patterns": [ + { + "include": "source.css.scss" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_shell": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(shell|sh|bash|zsh|bashrc|bash_profile|bash_login|profile|bash_logout|.textmate_init|\\{\\.bash.+?\\})((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.shellscript", + "patterns": [ + { + "include": "source.shell" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_sql": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(sql|ddl|dml)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.sql", + "patterns": [ + { + "include": "source.sql" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_swift": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(swift)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.swift", + "patterns": [ + { + "include": "source.swift" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_ts": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(typescript|ts)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.typescript", + "patterns": [ + { + "include": "source.ts" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_tsx": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(tsx)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.typescriptreact", + "patterns": [ + { + "include": "source.tsx" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_twig": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(twig)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.twig", + "patterns": [ + { + "include": "source.twig" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_unknown": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?=([^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown" + }, + "fenced_code_block_vs_net": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(vb)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.vs_net", + "patterns": [ + { + "include": "source.asp.vb.net" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_xml": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(xml|xsd|tld|jsp|pt|cpt|dtml|rss|opml)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.xml", + "patterns": [ + { + "include": "text.xml" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_xsl": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(xsl|xslt)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.xsl", + "patterns": [ + { + "include": "text.xml.xsl" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "fenced_code_block_yaml": { + "begin": "(^|\\G)(\\s*)(`{3,}|~{3,})\\s*(?i:(yaml|yml)((\\s+|:|,|\\{|\\?)[^`]*)?$)", + "beginCaptures": { + "3": { + "name": "punctuation.definition.markdown" + }, + "4": { + "name": "fenced_code.block.language.markdown" + }, + "5": { + "name": "fenced_code.block.language.attributes.markdown" + } + }, + "end": "(^|\\G)(\\2|\\s{0,3})(\\3)\\s*$", + "endCaptures": { + "3": { + "name": "punctuation.definition.markdown" + } + }, + "name": "markup.fenced_code.block.markdown", + "patterns": [ + { + "begin": "(^|\\G)(\\s*)(.*)", + "contentName": "meta.embedded.block.yaml", + "patterns": [ + { + "include": "source.yaml" + } + ], + "while": "(^|\\G)(?!\\s*([`~]{3,})\\s*$)" + } + ] + }, + "frontMatter": { + "applyEndPatternLast": true, + "begin": "\\A(?=(-{3,}))", + "end": "^ {,3}\\1-*[ \\t]*$|^[ \\t]*\\.{3}$", + "endCaptures": { + "0": { + "name": "punctuation.definition.end.frontmatter" + } + }, + "patterns": [ + { + "begin": "\\A(-{3,})(.*)$", + "beginCaptures": { + "1": { + "name": "punctuation.definition.begin.frontmatter" + }, + "2": { + "name": "comment.frontmatter" + } + }, + "contentName": "meta.embedded.block.frontmatter", + "patterns": [ + { + "include": "source.yaml" + } + ], + "while": "^(?! {,3}\\1-*[ \\t]*$|[ \\t]*\\.{3}$)" + } + ] + }, + "heading": { + "captures": { + "1": { + "patterns": [ + { + "captures": { + "1": { + "name": "punctuation.definition.heading.markdown" + }, + "2": { + "name": "entity.name.section.markdown", + "patterns": [ + { + "include": "#inline" + }, + { + "include": "text.html.derivative" + } + ] + }, + "3": { + "name": "punctuation.definition.heading.markdown" + } + }, + "match": "(#{6})\\s+(.*?)(?:\\s+(#+))?\\s*$", + "name": "heading.6.markdown" + }, + { + "captures": { + "1": { + "name": "punctuation.definition.heading.markdown" + }, + "2": { + "name": "entity.name.section.markdown", + "patterns": [ + { + "include": "#inline" + }, + { + "include": "text.html.derivative" + } + ] + }, + "3": { + "name": "punctuation.definition.heading.markdown" + } + }, + "match": "(#{5})\\s+(.*?)(?:\\s+(#+))?\\s*$", + "name": "heading.5.markdown" + }, + { + "captures": { + "1": { + "name": "punctuation.definition.heading.markdown" + }, + "2": { + "name": "entity.name.section.markdown", + "patterns": [ + { + "include": "#inline" + }, + { + "include": "text.html.derivative" + } + ] + }, + "3": { + "name": "punctuation.definition.heading.markdown" + } + }, + "match": "(#{4})\\s+(.*?)(?:\\s+(#+))?\\s*$", + "name": "heading.4.markdown" + }, + { + "captures": { + "1": { + "name": "punctuation.definition.heading.markdown" + }, + "2": { + "name": "entity.name.section.markdown", + "patterns": [ + { + "include": "#inline" + }, + { + "include": "text.html.derivative" + } + ] + }, + "3": { + "name": "punctuation.definition.heading.markdown" + } + }, + "match": "(#{3})\\s+(.*?)(?:\\s+(#+))?\\s*$", + "name": "heading.3.markdown" + }, + { + "captures": { + "1": { + "name": "punctuation.definition.heading.markdown" + }, + "2": { + "name": "entity.name.section.markdown", + "patterns": [ + { + "include": "#inline" + }, + { + "include": "text.html.derivative" + } + ] + }, + "3": { + "name": "punctuation.definition.heading.markdown" + } + }, + "match": "(#{2})\\s+(.*?)(?:\\s+(#+))?\\s*$", + "name": "heading.2.markdown" + }, + { + "captures": { + "1": { + "name": "punctuation.definition.heading.markdown" + }, + "2": { + "name": "entity.name.section.markdown", + "patterns": [ + { + "include": "#inline" + }, + { + "include": "text.html.derivative" + } + ] + }, + "3": { + "name": "punctuation.definition.heading.markdown" + } + }, + "match": "(#{1})\\s+(.*?)(?:\\s+(#+))?\\s*$", + "name": "heading.1.markdown" + } + ] + } + }, + "match": "(?:^|\\G)[ ]{0,3}(#{1,6}\\s+(.*?)(\\s+#{1,6})?\\s*)$", + "name": "markup.heading.markdown" + }, + "heading-setext": { + "patterns": [ + { + "match": "^(={3,})(?=[ \\t]*$\\n?)", + "name": "markup.heading.setext.1.markdown" + }, + { + "match": "^(-{3,})(?=[ \\t]*$\\n?)", + "name": "markup.heading.setext.2.markdown" + } + ] + }, + "html": { + "patterns": [ + { + "begin": "(^|\\G)\\s*(<!--)", + "captures": { + "1": { + "name": "punctuation.definition.comment.html" + }, + "2": { + "name": "punctuation.definition.comment.html" + } + }, + "end": "(-->)", + "name": "comment.block.html" + }, + { + "begin": "(?i)(^|\\G)\\s*(?=<(script|style|pre)(\\s|$|>)(?!.*?</(script|style|pre)>))", + "end": "(?i)(.*)((</)(script|style|pre)(>))", + "endCaptures": { + "1": { + "patterns": [ + { + "include": "text.html.derivative" + } + ] + }, + "2": { + "name": "meta.tag.structure.$4.end.html" + }, + "3": { + "name": "punctuation.definition.tag.begin.html" + }, + "4": { + "name": "entity.name.tag.html" + }, + "5": { + "name": "punctuation.definition.tag.end.html" + } + }, + "patterns": [ + { + "begin": "(\\s*|$)", + "patterns": [ + { + "include": "text.html.derivative" + } + ], + "while": "(?i)^(?!.*</(script|style|pre)>)" + } + ] + }, + { + "begin": "(?i)(^|\\G)\\s*(?=</?[a-zA-Z]+[^\\s/>]*(\\s|$|/?>))", + "patterns": [ + { + "include": "text.html.derivative" + } + ], + "while": "^(?!\\s*$)" + }, + { + "begin": "(^|\\G)\\s*(?=(<[a-zA-Z0-9\\-](/?>|\\s.*?>)|</[a-zA-Z0-9\\-]>)\\s*$)", + "patterns": [ + { + "include": "text.html.derivative" + } + ], + "while": "^(?!\\s*$)" + } + ] + }, + "image-inline": { + "captures": { + "1": { + "name": "punctuation.definition.link.description.begin.markdown" + }, + "2": { + "name": "string.other.link.description.markdown" + }, + "4": { + "name": "punctuation.definition.link.description.end.markdown" + }, + "5": { + "name": "punctuation.definition.metadata.markdown" + }, + "7": { + "name": "punctuation.definition.link.markdown" + }, + "8": { + "name": "markup.underline.link.image.markdown" + }, + "9": { + "name": "punctuation.definition.link.markdown" + }, + "10": { + "name": "markup.underline.link.image.markdown" + }, + "12": { + "name": "string.other.link.description.title.markdown" + }, + "13": { + "name": "punctuation.definition.string.begin.markdown" + }, + "14": { + "name": "punctuation.definition.string.end.markdown" + }, + "15": { + "name": "string.other.link.description.title.markdown" + }, + "16": { + "name": "punctuation.definition.string.begin.markdown" + }, + "17": { + "name": "punctuation.definition.string.end.markdown" + }, + "18": { + "name": "string.other.link.description.title.markdown" + }, + "19": { + "name": "punctuation.definition.string.begin.markdown" + }, + "20": { + "name": "punctuation.definition.string.end.markdown" + }, + "21": { + "name": "punctuation.definition.metadata.markdown" + } + }, + "match": "(!\\[)((?<square>[^\\[\\]\\\\]|\\\\.|\\[\\g<square>*+\\])*+)(\\])(\\()[ \\t]*((<)((?:\\\\[<>]|[^<>\\n])*)(>)|((?<url>(?>[^\\s()]+)|\\(\\g<url>*\\))*))[ \\t]*(?:((\\().+?(\\)))|((\").+?(\"))|((').+?(')))?\\s*(\\))", + "name": "meta.image.inline.markdown" + }, + "image-ref": { + "captures": { + "1": { + "name": "punctuation.definition.link.description.begin.markdown" + }, + "2": { + "name": "string.other.link.description.markdown" + }, + "4": { + "name": "punctuation.definition.link.description.end.markdown" + }, + "5": { + "name": "punctuation.definition.constant.markdown" + }, + "6": { + "name": "constant.other.reference.link.markdown" + }, + "7": { + "name": "punctuation.definition.constant.markdown" + } + }, + "match": "(!\\[)((?<square>[^\\[\\]\\\\]|\\\\.|\\[\\g<square>*+\\])*+)(\\])[ ]?(\\[)(.*?)(\\])", + "name": "meta.image.reference.markdown" + }, + "inline": { + "patterns": [ + { + "include": "#tag" + }, + { + "include": "#attribute" + }, + { + "include": "#ampersand" + }, + { + "include": "#bracket" + }, + { + "include": "#bold" + }, + { + "include": "#italic" + }, + { + "include": "#raw" + }, + { + "include": "#strikethrough" + }, + { + "include": "#escape" + }, + { + "include": "#image-inline" + }, + { + "include": "#image-ref" + }, + { + "include": "#link-email" + }, + { + "include": "#link-inet" + }, + { + "include": "#link-inline" + }, + { + "include": "#link-ref" + }, + { + "include": "#link-ref-literal" + }, + { + "include": "#link-ref-shortcut" + } + ] + }, + "italic": { + "begin": "(?<open>(\\*(?=\\w)|(?<!\\w)\\*|(?<!\\w)\\b_))(?=\\S)(?=(<[^>]*+>|(?<raw>`+)([^`]|(?!(?<!`)\\k<raw>(?!`))`)*+\\k<raw>|\\\\[\\\\`*_{}\\[\\]()#.!+\\->]?+|\\[((?<square>[^\\[\\]\\\\]|\\\\.|\\[\\g<square>*+\\])*+\\](([ ]?\\[[^\\]]*+\\])|(\\([ \\t]*+<?(.*?)>?[ \\t]*+((?<title>['\"])(.*?)\\k<title>)?\\))))|\\k<open>\\k<open>|(?!(?<=\\S)\\k<open>).)++(?<=\\S)(?=_\\b|\\*)\\k<open>)", + "captures": { + "1": { + "name": "punctuation.definition.italic.markdown" + } + }, + "end": "(?<=\\S)(\\1)((?!\\1)|(?=\\1\\1))", + "name": "markup.italic.markdown", + "patterns": [ + { + "applyEndPatternLast": true, + "begin": "(?=<[^>]*?>)", + "end": "(?<=>)", + "patterns": [ + { + "include": "text.html.derivative" + } + ] + }, + { + "include": "#escape" + }, + { + "include": "#ampersand" + }, + { + "include": "#bracket" + }, + { + "include": "#raw" + }, + { + "include": "#bold" + }, + { + "include": "#image-inline" + }, + { + "include": "#link-inline" + }, + { + "include": "#link-inet" + }, + { + "include": "#link-email" + }, + { + "include": "#image-ref" + }, + { + "include": "#link-ref-literal" + }, + { + "include": "#link-ref" + }, + { + "include": "#link-ref-shortcut" + }, + { + "include": "#strikethrough" + } + ] + }, + "link-def": { + "captures": { + "1": { + "name": "punctuation.definition.constant.markdown" + }, + "2": { + "name": "constant.other.reference.link.markdown" + }, + "3": { + "name": "punctuation.definition.constant.markdown" + }, + "4": { + "name": "punctuation.separator.key-value.markdown" + }, + "5": { + "name": "punctuation.definition.link.markdown" + }, + "6": { + "name": "markup.underline.link.markdown" + }, + "7": { + "name": "punctuation.definition.link.markdown" + }, + "8": { + "name": "markup.underline.link.markdown" + }, + "9": { + "name": "string.other.link.description.title.markdown" + }, + "10": { + "name": "punctuation.definition.string.begin.markdown" + }, + "11": { + "name": "punctuation.definition.string.end.markdown" + }, + "12": { + "name": "string.other.link.description.title.markdown" + }, + "13": { + "name": "punctuation.definition.string.begin.markdown" + }, + "14": { + "name": "punctuation.definition.string.end.markdown" + }, + "15": { + "name": "string.other.link.description.title.markdown" + }, + "16": { + "name": "punctuation.definition.string.begin.markdown" + }, + "17": { + "name": "punctuation.definition.string.end.markdown" + } + }, + "match": "\\s*(\\[)([^]]+?)(\\])(:)[ \\t]*(?:(<)((?:\\\\[<>]|[^<>\\n])*)(>)|(\\S+?))[ \\t]*(?:((\\().+?(\\)))|((\").+?(\"))|((').+?(')))?\\s*$", + "name": "meta.link.reference.def.markdown" + }, + "link-email": { + "captures": { + "1": { + "name": "punctuation.definition.link.markdown" + }, + "2": { + "name": "markup.underline.link.markdown" + }, + "4": { + "name": "punctuation.definition.link.markdown" + } + }, + "match": "(<)((?:mailto:)?[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*)(>)", + "name": "meta.link.email.lt-gt.markdown" + }, + "link-inet": { + "captures": { + "1": { + "name": "punctuation.definition.link.markdown" + }, + "2": { + "name": "markup.underline.link.markdown" + }, + "3": { + "name": "punctuation.definition.link.markdown" + } + }, + "match": "(<)((?:https?|ftp)://.*?)(>)", + "name": "meta.link.inet.markdown" + }, + "link-inline": { + "captures": { + "1": { + "name": "punctuation.definition.link.title.begin.markdown" + }, + "2": { + "name": "string.other.link.title.markdown", + "patterns": [ + { + "include": "#raw" + }, + { + "include": "#bold" + }, + { + "include": "#italic" + }, + { + "include": "#strikethrough" + }, + { + "include": "#image-inline" + } + ] + }, + "4": { + "name": "punctuation.definition.link.title.end.markdown" + }, + "5": { + "name": "punctuation.definition.metadata.markdown" + }, + "7": { + "name": "punctuation.definition.link.markdown" + }, + "8": { + "name": "markup.underline.link.markdown" + }, + "9": { + "name": "punctuation.definition.link.markdown" + }, + "10": { + "name": "markup.underline.link.markdown" + }, + "12": { + "name": "string.other.link.description.title.markdown" + }, + "13": { + "name": "punctuation.definition.string.begin.markdown" + }, + "14": { + "name": "punctuation.definition.string.end.markdown" + }, + "15": { + "name": "string.other.link.description.title.markdown" + }, + "16": { + "name": "punctuation.definition.string.begin.markdown" + }, + "17": { + "name": "punctuation.definition.string.end.markdown" + }, + "18": { + "name": "string.other.link.description.title.markdown" + }, + "19": { + "name": "punctuation.definition.string.begin.markdown" + }, + "20": { + "name": "punctuation.definition.string.end.markdown" + }, + "21": { + "name": "punctuation.definition.metadata.markdown" + } + }, + "match": "(\\[)((?<square>[^\\[\\]\\\\]|\\\\.|\\[\\g<square>*+\\])*+)(\\])(\\()[ \\t]*((<)((?:\\\\[<>]|[^<>\\n])*)(>)|((?<url>(?>[^\\s()]+)|\\(\\g<url>*\\))*))[ \\t]*(?:((\\()[^()]*(\\)))|((\")[^\"]*(\"))|((')[^']*(')))?\\s*(\\))", + "name": "meta.link.inline.markdown" + }, + "link-ref": { + "captures": { + "1": { + "name": "punctuation.definition.link.title.begin.markdown" + }, + "2": { + "name": "string.other.link.title.markdown", + "patterns": [ + { + "include": "#raw" + }, + { + "include": "#bold" + }, + { + "include": "#italic" + }, + { + "include": "#strikethrough" + }, + { + "include": "#image-inline" + } + ] + }, + "4": { + "name": "punctuation.definition.link.title.end.markdown" + }, + "5": { + "name": "punctuation.definition.constant.begin.markdown" + }, + "6": { + "name": "constant.other.reference.link.markdown" + }, + "7": { + "name": "punctuation.definition.constant.end.markdown" + } + }, + "match": "(?<![\\]\\\\])(\\[)((?<square>[^\\[\\]\\\\]|\\\\.|\\[\\g<square>*+\\])*+)(\\])(\\[)([^\\]]*+)(\\])", + "name": "meta.link.reference.markdown" + }, + "link-ref-literal": { + "captures": { + "1": { + "name": "punctuation.definition.link.title.begin.markdown" + }, + "2": { + "name": "string.other.link.title.markdown" + }, + "4": { + "name": "punctuation.definition.link.title.end.markdown" + }, + "5": { + "name": "punctuation.definition.constant.begin.markdown" + }, + "6": { + "name": "punctuation.definition.constant.end.markdown" + } + }, + "match": "(?<![\\]\\\\])(\\[)((?<square>[^\\[\\]\\\\]|\\\\.|\\[\\g<square>*+\\])*+)(\\])[ ]?(\\[)(\\])", + "name": "meta.link.reference.literal.markdown" + }, + "link-ref-shortcut": { + "captures": { + "1": { + "name": "punctuation.definition.link.title.begin.markdown" + }, + "2": { + "name": "string.other.link.title.markdown" + }, + "3": { + "name": "punctuation.definition.link.title.end.markdown" + } + }, + "match": "(?<![\\]\\\\])(\\[)((?:[^\\s\\[\\]\\\\]|\\\\[\\[\\]])+?)((?<!\\\\)\\])", + "name": "meta.link.reference.markdown" + }, + "list_paragraph": { + "begin": "(^|\\G)(?=\\S)(?![*+->]\\s|\\d+\\.\\s)", + "name": "meta.paragraph.markdown", + "patterns": [ + { + "include": "#inline" + }, + { + "include": "text.html.derivative" + }, + { + "include": "#heading-setext" + } + ], + "while": "(^|\\G)(?!\\s*$|#|[ ]{0,3}([-*_>][ ]{2,}){3,}[ \\t]*$\\n?|[ ]{0,3}[*+->]|[ ]{0,3}\\d+\\.)" + }, + "lists": { + "patterns": [ + { + "begin": "(^|\\G)([ ]{0,3})([*+-])([ \\t])", + "beginCaptures": { + "3": { + "name": "punctuation.definition.list.begin.markdown" + } + }, + "comment": "Currently does not support un-indented second lines.", + "name": "markup.list.unnumbered.markdown", + "patterns": [ + { + "include": "#block" + }, + { + "include": "#list_paragraph" + } + ], + "while": "((^|\\G)([ ]{2,4}|\\t))|(^[ \\t]*$)" + }, + { + "begin": "(^|\\G)([ ]{0,3})(\\d+[\\.)])([ \\t])", + "beginCaptures": { + "3": { + "name": "punctuation.definition.list.begin.markdown" + } + }, + "name": "markup.list.numbered.markdown", + "patterns": [ + { + "include": "#block" + }, + { + "include": "#list_paragraph" + } + ], + "while": "((^|\\G)([ ]{2,4}|\\t))|(^[ \\t]*$)" + } + ] + }, + "paragraph": { + "begin": "(^|\\G)[ ]{0,3}(?=[^ \\t\\n])", + "name": "meta.paragraph.markdown", + "patterns": [ + { + "include": "#inline" + }, + { + "include": "text.html.derivative" + }, + { + "include": "#heading-setext" + } + ], + "while": "(^|\\G)((?=\\s*[-=]{3,}\\s*$)|[ ]{4,}(?=[^ \\t\\n]))" + }, + "raw": { + "captures": { + "1": { + "name": "punctuation.definition.raw.markdown" + }, + "3": { + "name": "punctuation.definition.raw.markdown" + } + }, + "match": "(`+)((?:[^`]|(?!(?<!`)\\1(?!`))`)*+)(\\1)", + "name": "markup.inline.raw.string.markdown" + }, + "raw_block": { + "begin": "(^|\\G)([ ]{4}|\\t)", + "name": "markup.raw.block.markdown", + "while": "(^|\\G)([ ]{4}|\\t)" + }, + "separator": { + "match": "(^|\\G)[ ]{0,3}([\\*\\-_])([ ]{0,2}\\2){2,}[ \\t]*$\\n?", + "name": "meta.separator.markdown" + }, + "strikethrough": { + "captures": { + "1": { + "name": "punctuation.definition.strikethrough.markdown" + }, + "2": { + "patterns": [ + { + "applyEndPatternLast": true, + "begin": "(?=<[^>]*?>)", + "end": "(?<=>)", + "patterns": [ + { + "include": "text.html.derivative" + } + ] + }, + { + "include": "#escape" + }, + { + "include": "#ampersand" + }, + { + "include": "#bracket" + }, + { + "include": "#raw" + }, + { + "include": "#bold" + }, + { + "include": "#italic" + }, + { + "include": "#image-inline" + }, + { + "include": "#link-inline" + }, + { + "include": "#link-inet" + }, + { + "include": "#link-email" + }, + { + "include": "#image-ref" + }, + { + "include": "#link-ref-literal" + }, + { + "include": "#link-ref" + }, + { + "include": "#link-ref-shortcut" + } + ] + }, + "3": { + "name": "punctuation.definition.strikethrough.markdown" + } + }, + "match": "(?<!\\\\)(~{2,})((?:[^~]|(?!(?<![~\\\\])\\1(?!~))~)*+)(\\1)", + "name": "markup.strikethrough.markdown" + }, + "table": { + "begin": "(^|\\G)(\\|)(?=[^|].+\\|\\s*$)", + "beginCaptures": { + "2": { + "name": "punctuation.definition.table.markdown" + } + }, + "name": "markup.table.markdown", + "patterns": [ + { + "match": "\\|", + "name": "punctuation.definition.table.markdown" + }, + { + "captures": { + "1": { + "name": "punctuation.separator.table.markdown" + } + }, + "match": "(?<=\\|)\\s*(:?-+:?)\\s*(?=\\|)" + }, + { + "captures": { + "1": { + "patterns": [ + { + "include": "#inline" + } + ] + } + }, + "match": "(?<=\\|)\\s*(?=\\S)((\\\\\\||[^|])+)(?<=\\S)\\s*(?=\\|)" + } + ], + "while": "(^|\\G)(?=\\|)" + }, + "shortcut": { + "match": "(\\$|\\.|#)([-_:a-zA-Z0-9]+)", + "name": "string.other.markdoc-shortcut" + }, + "attribute": { + "match": "([-_a-zA-Z0-9]+)(=)", + "captures": { + "1": { + "name": "entity.other.attribute-name" + }, + "2": { + "name": "punctuation.definition.tag.equal.markdoc" + } + } + }, + "tag": { + "name": "punctuation.definition.tag", + "begin": "({%)\\s*/?([-_a-zA-Z0-9]+)?", + "end": "\\s*/?\\s*%}", + "beginCaptures": { + "1": { + "name": "punctuation.definition.tag.begin.markdoc" + }, + "2": { + "name": "entity.name.tag" + } + }, + "endCaptures": { + "0": { + "name": "punctuation.definition.tag.end.markdoc" + } + }, + "patterns": [ + { + "include": "#attribute" + }, + { + "include": "#shortcut" + }, + { + "include": "source.json" + } + ] + } + }, + "scopeName": "text.html.markdoc" +}
\ No newline at end of file diff --git a/docs/package.json b/docs/package.json index 74275bdb..406383ba 100644 --- a/docs/package.json +++ b/docs/package.json @@ -11,7 +11,8 @@ "build": "astro build", "preview": "astro preview", "astro": "astro", - "lunaria:build": "lunaria build" + "lunaria:build": "lunaria build", + "grammars": "node grammars/generate.mjs" }, "dependencies": { "@astro-community/astro-embed-youtube": "^0.5.2", diff --git a/docs/public/_redirects b/docs/public/_redirects index f62b0d9a..1e26cc68 100644 --- a/docs/public/_redirects +++ b/docs/public/_redirects @@ -6,6 +6,10 @@ /showcase/ /resources/showcase/ /:lang/showcase/ /:lang/resources/showcase/ +# Component docs +/guides/components/ /components/using-components/ +/:lang/guides/components/ /:lang/components/using-components/ + # Translated 404s /:lang/* /:lang/404/ 404 /* /404/ 404 diff --git a/docs/src/components/component-preview.astro b/docs/src/components/component-preview.astro new file mode 100644 index 00000000..41d71815 --- /dev/null +++ b/docs/src/components/component-preview.astro @@ -0,0 +1,49 @@ +--- +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +const showContentTypeTabs = Astro.slots.has('markdoc'); +--- + +<figure> + { + showContentTypeTabs ? ( + <Tabs syncKey="content-type"> + <TabItem label="MDX"> + <slot /> + </TabItem> + <TabItem label="Markdoc"> + <slot name="markdoc" /> + </TabItem> + </Tabs> + ) : ( + <slot /> + ) + } + <div class="preview"> + <figcaption>{Astro.locals.t('component.preview')}</figcaption> + <div class="preview-content"><slot name="preview" /></div> + </div> +</figure> + +<style> + :global(.sl-markdown-content) .preview { + border: 1px solid var(--sl-color-gray-5); + border-top: none; + margin-top: 0; + } + + .preview:only-child { + border-top: 1px solid var(--sl-color-gray-5); + } + + figcaption { + font-size: var(--sl-text-sm); + font-weight: 600; + padding: 0.5rem 1rem 0; + } + + :global(.sl-markdown-content) .preview-content { + margin-top: 0; + padding: 1rem; + } +</style> diff --git a/docs/src/components/icons-list.astro b/docs/src/components/icons-list.astro index 09b0a699..05caeedf 100644 --- a/docs/src/components/icons-list.astro +++ b/docs/src/components/icons-list.astro @@ -23,8 +23,7 @@ const icons = Object.keys(Icons) as (keyof typeof Icons)[]; icons.forEach((icon) => { icon.addEventListener('click', () => { const iconName = icon.dataset.name!; - const copiedValue = `<Icon name="${iconName}" />`; - navigator.clipboard.writeText(copiedValue); + navigator.clipboard.writeText(iconName); const iconLabel = icon.querySelector('[aria-live]'); if (iconLabel) { diff --git a/docs/src/content/config.ts b/docs/src/content/config.ts index 9df91b60..e56c2a20 100644 --- a/docs/src/content/config.ts +++ b/docs/src/content/config.ts @@ -1,7 +1,14 @@ -import { defineCollection } from 'astro:content'; +import { defineCollection, z } from 'astro:content'; import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; export const collections = { docs: defineCollection({ schema: docsSchema() }), - i18n: defineCollection({ type: 'data', schema: i18nSchema() }), + i18n: defineCollection({ + type: 'data', + schema: i18nSchema({ + extend: z.object({ + 'component.preview': z.string().optional(), + }), + }), + }), }; diff --git a/docs/src/content/docs/components/asides.mdx b/docs/src/content/docs/components/asides.mdx new file mode 100644 index 00000000..a28375b0 --- /dev/null +++ b/docs/src/content/docs/components/asides.mdx @@ -0,0 +1,158 @@ +--- +title: Asides +description: Learn how to use asides in Starlight to display secondary information alongside a page’s main content. +--- + +import { Aside } from '@astrojs/starlight/components'; + +To display secondary information alongside a page’s main content, use the `<Aside>` component. + +import Preview from '~/components/component-preview.astro'; + +<Preview> + +<Aside slot="preview"> + Include nonessential, supplementary information in an `<Aside>`. +</Aside> + +</Preview> + +## Import + +```tsx +import { Aside } from '@astrojs/starlight/components'; +``` + +## Usage + +Display an aside (also known as “admonitions” or “callouts”) using the `<Aside>` component. + +An `<Aside>` can have an optional [`type`](#type) attribute, which controls the aside’s color, icon, and default title. + +<Preview> + +````mdx +import { Aside } from '@astrojs/starlight/components'; + +<Aside>Some content in an aside.</Aside> + +<Aside type="caution">Some cautionary content.</Aside> + +<Aside type="tip"> + +Other content is also supported in asides. + +```js +// A code snippet, for example. +``` + +</Aside> + +<Aside type="danger">Do not give your password to anyone.</Aside> +```` + +<Fragment slot="markdoc"> + +````markdoc +{% aside %} +Some content in an aside. +{% /aside %} + +{% aside type="caution" %} +Some cautionary content. +{% /aside %} + +{% aside type="tip" %} +Other content is also supported in asides. + +```js +// A code snippet, for example. +``` +{% /aside %} + +{% aside type="danger" %} +Do not give your password to anyone. +{% /aside %} +```` + +</Fragment> + +<Fragment slot="preview"> + + <Aside>Some content in an aside.</Aside> + + <Aside type="caution">Some cautionary content.</Aside> + + <Aside type="tip"> + + Other content is also supported in asides. + + ```js + // A code snippet, for example. + ``` + + </Aside> + + <Aside type="danger">Do not give your password to anyone.</Aside> + +</Fragment> + +</Preview> + +Starlight also provides a custom syntax for rendering asides in Markdown and MDX as an alternative to the `<Aside>` component. +See the [“Authoring Content in Markdown”](/guides/authoring-content/#asides) guide for details of the custom syntax. + +### Use custom titles + +Override the default aside titles by using the [`title`](#title) attribute. + +<Preview> + +```mdx 'title="Watch out!"' +import { Aside } from '@astrojs/starlight/components'; + +<Aside type="caution" title="Watch out!"> + A warning aside *with* a custom title. +</Aside> +``` + +<Fragment slot="markdoc"> + +```markdoc 'title="Watch out!"' +{% aside type="caution" title="Watch out!" %} +A warning aside *with* a custom title. +{% /aside %} +``` + +</Fragment> + +<Aside slot="preview" type="caution" title="Watch out!"> + A warning aside *with* a custom title. +</Aside> + +</Preview> + +## `<Aside>` Props + +**Implementation:** [`Aside.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/Aside.astro) + +The `<Aside>` component accepts the following props: + +### `type` + +**type:** `'note' | 'tip' | 'caution' | 'danger'` +**default:** `'note'` + +The type of aside to display: + +- `note` asides (the default) are blue and display an information icon. +- `tip` asides are purple and display a rocket icon. +- `caution` asides are yellow and display a triangular warning icon. +- `danger` asides are red and display an octagonal warning icon. + +### `title` + +**type:** `string` + +The title of the aside to display. +If `title` is not set, the default title for the current aside `type` will be used. diff --git a/docs/src/content/docs/components/badges.mdx b/docs/src/content/docs/components/badges.mdx new file mode 100644 index 00000000..1c95f570 --- /dev/null +++ b/docs/src/content/docs/components/badges.mdx @@ -0,0 +1,150 @@ +--- +title: Badges +description: Learn how to use badges in Starlight to display additional pieces of information. +--- + +import { Badge } from '@astrojs/starlight/components'; + +To display small pieces of information, such as a status or category, use the `<Badge>` component. + +import Preview from '~/components/component-preview.astro'; + +<Preview> + +<Badge slot="preview" text="New" /> + +</Preview> + +## Import + +```tsx +import { Badge } from '@astrojs/starlight/components'; +``` + +## Usage + +Display a badge using the `<Badge>` component and pass the content you want to display to the [`text`](#text) attribute of the `<Badge>` component. + +By default, the badge will use the theme accent color of your site. +To use a built-in badge color, set the [`variant`](#variant) attribute to one of the supported values. + +<Preview> + +```mdx +import { Badge } from '@astrojs/starlight/components'; + +<Badge text="Note" variant="note" /> +<Badge text="Success" variant="success" /> +<Badge text="Tip" variant="tip" /> +<Badge text="Caution" variant="caution" /> +<Badge text="Danger" variant="danger" /> +``` + +<Fragment slot="markdoc"> + +```markdoc +{% badge text="Note" variant="note" /%} +{% badge text="Success" variant="success" /%} +{% badge text="Tip" variant="tip" /%} +{% badge text="Caution" variant="caution" /%} +{% badge text="Danger" variant="danger" /%} +``` + +</Fragment> + +<Fragment slot="preview"> + <Badge text="Note" variant="note" /> + <Badge text="Success" variant="success" /> + <Badge text="Tip" variant="tip" /> + <Badge text="Caution" variant="caution" /> + <Badge text="Danger" variant="danger" /> +</Fragment> + +</Preview> + +### Use different sizes + +Use the [`size`](#size) attribute to control the size of the badge text. + +<Preview> + +```mdx /size="\w+"/ +import { Badge } from '@astrojs/starlight/components'; + +<Badge text="New" size="small" /> +<Badge text="New and improved" size="medium" /> +<Badge text="New, improved, and bigger" size="large" /> +``` + +<Fragment slot="markdoc"> + +```markdoc /size="\w+"/ +{% badge text="New" size="small" /%} +{% badge text="New and improved" size="medium" /%} +{% badge text="New, improved, and bigger" size="large" /%} +``` + +</Fragment> + +<Fragment slot="preview"> + <Badge text="New" size="small" /> + <Badge text="New and improved" size="medium" /> + <Badge text="New, improved, and bigger" size="large" /> +</Fragment> + +</Preview> + +### Customize badges + +Customize badges by using any other `<span>` attributes such as `class` or `style` with custom CSS. + +<Preview> + +```mdx "style={{ fontStyle: 'italic' }}" +import { Badge } from '@astrojs/starlight/components'; + +<Badge text="Custom" variant="success" style={{ fontStyle: 'italic' }} /> +``` + +<Fragment slot="markdoc"> + +```markdoc 'style="font-style: italic;"' +{% badge text="Custom" variant="success" style="font-style: italic;" /%} +``` + +</Fragment> + +<Badge + slot="preview" + text="Custom" + variant="success" + style={{ fontStyle: 'italic' }} +/> + +</Preview> + +## `<Badge>` Props + +**Implementation:** [`Badge.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/Badge.astro) + +The `<Badge>` component accepts the following props and also any [other `<span>` attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes): + +### `text` + +**required** +**type:** `string` + +The text content to display in the badge. + +### `variant` + +**type:** `'note' | 'danger' | 'success' | 'caution' | 'tip' | 'default'` +**default:** `'default'` + +The badge color variant to use: `note` (blue), `tip` (purple), `danger` (red), `caution` (orange), `success` (green), or `default` (theme accent color). + +### `size` + +**type:** `'small' | 'medium' | 'large'` + +Defines the size of the badge to display. diff --git a/docs/src/content/docs/components/card-grids.mdx b/docs/src/content/docs/components/card-grids.mdx new file mode 100644 index 00000000..1485174e --- /dev/null +++ b/docs/src/content/docs/components/card-grids.mdx @@ -0,0 +1,173 @@ +--- +title: Card Grids +description: Learn how to wrap multiple cards in a grid in Starlight. +sidebar: + order: 4 +--- + +import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components'; + +To wrap multiple [`<Card>`](/components/cards/) or [`<LinkCard>`](/components/link-cards/) components in a grid, use the`<CardGrid>` component. + +import Preview from '~/components/component-preview.astro'; + +<Preview> + +<CardGrid slot="preview"> + <Card title="Stars" icon="star"> + Sirius, Vega, Betelgeuse + </Card> + <Card title="Moons" icon="moon"> + Io, Europa, Ganymede + </Card> +</CardGrid> + +</Preview> + +## Import + +```tsx +import { CardGrid } from '@astrojs/starlight/components'; +``` + +## Usage + +### Group cards + +Display multiple [`<Card>`](/components/cards/) components side-by-side when there’s enough space by grouping them using the `<CardGrid>` component. + +<Preview> + +```mdx {3,10} +import { Card, CardGrid } from '@astrojs/starlight/components'; + +<CardGrid> + <Card title="Check this out" icon="open-book"> + Interesting content you want to highlight. + </Card> + <Card title="Other feature" icon="information"> + More information you want to share. + </Card> +</CardGrid> +``` + +<Fragment slot="markdoc"> + +```markdoc {1,9} +{% cardgrid %} +{% card title="Check this out" icon="open-book" %} +Interesting content you want to highlight. +{% /card %} + +{% card title="Other feature" icon="information" %} +More information you want to share. +{% /card %} +{% /cardgrid %} +``` + +</Fragment> + +<CardGrid slot="preview"> + <Card title="Check this out" icon="open-book"> + Interesting content you want to highlight. + </Card> + <Card title="Other feature" icon="information"> + More information you want to share. + </Card> +</CardGrid> + +</Preview> + +### Group link cards + +Display multiple [`<LinkCard>`](/components/link-cards/) components side-by-side when there’s enough space by grouping them using the `<CardGrid>` component. + +<Preview> + +```mdx {3,6} +import { LinkCard, CardGrid } from '@astrojs/starlight/components'; + +<CardGrid> + <LinkCard title="Authoring Markdown" href="/guides/authoring-content/" /> + <LinkCard title="Components" href="/components/using-components/" /> +</CardGrid> +``` + +<Fragment slot="markdoc"> + +```markdoc {1,5} +{% cardgrid %} +{% linkcard title="Authoring Markdown" href="/guides/authoring-content/" /%} + +{% linkcard title="Components" href="/components/using-components/" /%} +{% /cardgrid %} +``` + +</Fragment> + +<CardGrid slot="preview"> + <LinkCard title="Authoring Markdown" href="/guides/authoring-content/" /> + <LinkCard title="Components" href="/components/using-components/" /> +</CardGrid> + +</Preview> + +### Stagger cards + +Shift the second column of the grid vertically to add visual interest by adding the [`stagger`](#stagger) attribute to the `<CardGrid>` component. + +This attribute is useful on your home page to display your project’s key features. + +<Preview> + +```mdx "stagger" +import { Card, CardGrid } from '@astrojs/starlight/components'; + +<CardGrid stagger> + <Card title="Check this out" icon="open-book"> + Interesting content you want to highlight. + </Card> + <Card title="Other feature" icon="information"> + More information you want to share. + </Card> +</CardGrid> +``` + +<Fragment slot="markdoc"> + +```markdoc "stagger=true" +{% cardgrid stagger=true %} +{% card title="Check this out" icon="open-book" %} +Interesting content you want to highlight. +{% /card %} + +{% card title="Other feature" icon="information" %} +More information you want to share. +{% /card %} +{% /cardgrid %} +``` + +</Fragment> + +<CardGrid slot="preview" stagger> + <Card title="Check this out" icon="open-book"> + Interesting content you want to highlight. + </Card> + <Card title="Other feature" icon="information"> + More information you want to share. + </Card> +</CardGrid> + +</Preview> + +## `<CardGrid>` Props + +**Implementation:** [`CardGrid.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/CardGrid.astro) + +The `<CardGrid>` component accepts the following props: + +### `stagger` + +**type:** `boolean` + +Defines whether to stagger the cards in the grid or not. diff --git a/docs/src/content/docs/components/cards.mdx b/docs/src/content/docs/components/cards.mdx new file mode 100644 index 00000000..0749d4e5 --- /dev/null +++ b/docs/src/content/docs/components/cards.mdx @@ -0,0 +1,108 @@ +--- +title: Cards +description: Learn how to use cards in Starlight to display content in a box. +sidebar: + order: 2 +--- + +import { Card } from '@astrojs/starlight/components'; + +To display content in a box matching Starlight’s styles, use the `<Card>` component. + +import Preview from '~/components/component-preview.astro'; + +<Preview> + +<Card slot="preview" title="Moons" icon="moon"> + Io, Europa, Ganymede +</Card> + +</Preview> + +## Import + +```tsx +import { Card } from '@astrojs/starlight/components'; +``` + +## Usage + +Display a card using the `<Card>` component and provide a [`title`](#title) for the card. + +<Preview> + +```mdx +import { Card } from '@astrojs/starlight/components'; + +<Card title="Check this out">Interesting content you want to highlight.</Card> +``` + +<Fragment slot="markdoc"> + +```markdoc +{% card title="Check this out" %} +Interesting content you want to highlight. +{% /card %} +``` + +</Fragment> + +<Card slot="preview" title="Check this out"> + Interesting content you want to highlight. +</Card> + +</Preview> + +### Add icons to cards + +Include an icon in a card using the [`icon`](#icon) attribute set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons). + +<Preview> + +```mdx 'icon="star"' +import { Card } from '@astrojs/starlight/components'; + +<Card title="Stars" icon="star"> + Sirius, Vega, Betelgeuse +</Card> +``` + +<Fragment slot="markdoc"> + +```markdoc 'icon="star"' +{% card title="Stars" icon="star" %} +Sirius, Vega, Betelgeuse +{% /card %} +``` + +</Fragment> + +<Card slot="preview" title="Stars" icon="star"> + Sirius, Vega, Betelgeuse +</Card> + +</Preview> + +### Group cards + +Display multiple cards side-by-side when there’s enough space by grouping them using the [`<CardGrid>`](/components/card-grids/) component. +See the [“Group cards”](/components/card-grids/#group-cards) guide for an example. + +## `<Card>` Props + +**Implementation:** [`Card.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/Card.astro) + +The `<Card>` component accepts the following props: + +### `title` + +**required** +**type:** `string` + +The title of the card to display. + +### `icon` + +**type:** `string` + +A card can include an `icon` attribute set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons). diff --git a/docs/src/content/docs/components/code.mdx b/docs/src/content/docs/components/code.mdx new file mode 100644 index 00000000..69798f2f --- /dev/null +++ b/docs/src/content/docs/components/code.mdx @@ -0,0 +1,103 @@ +--- +title: Code +description: Learn how to display syntax highlighted code in Starlight without Markdown code blocks. +--- + +import { Code } from '@astrojs/starlight/components'; + +The `<Code>` component renders syntax highlighted code. +It is useful when using a [Markdown code block](/guides/authoring-content/#code-blocks) is not possible, for example, to render data coming from external sources like files, databases, or APIs. + +import Preview from '~/components/component-preview.astro'; + +<Preview> + +<Code + slot="preview" + code={`## Welcome + +Hello from **space**!`} +lang="md" +title="example.md" +ins={3} +/> + +</Preview> + +## Import + +```tsx +import { Code } from '@astrojs/starlight/components'; +``` + +## Usage + +Use the `<Code>` component to render syntax highlighted code, for example when displaying code fetched from external sources. + +See the [Expressive Code “Code Component” docs](https://expressive-code.com/key-features/code-component/) for full details on how to use the `<Code>` component and the list of available props. + +<Preview> + +```mdx +import { Code } from '@astrojs/starlight/components'; + +export const exampleCode = `console.log('This could come from a file or CMS!');`; +export const fileName = 'example.js'; +export const highlights = ['file', 'CMS']; + +<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> +``` + +<Fragment slot="markdoc"> + +```markdoc +{% code + code="console.log('This could come from a file or CMS!');" + lang="js" + title="example.js" + meta="'file' 'CMS'" /%} +``` + +</Fragment> + +export const exampleCode = `console.log('This could come from a file or CMS!');`; +export const fileName = 'example.js'; +export const highlights = ['file', 'CMS']; + +<Code + slot="preview" + code={exampleCode} + lang="js" + title={fileName} + mark={highlights} +/> + +</Preview> + +### Display imported code + +In MDX files and Astro components, use [Vite’s `?raw` import suffix](https://vitejs.dev/guide/assets#importing-asset-as-string) to import any code file as a string. +You can then pass this imported string to the `<Code>` component to include it on your page. + +<Preview> + +```mdx "?raw" +# src/content/docs/example.mdx + +import { Code } from '@astrojs/starlight/components'; +import importedCode from '/src/env.d.ts?raw'; + +<Code code={importedCode} lang="ts" title="src/env.d.ts" /> +``` + +import importedCode from '/src/env.d.ts?raw'; + +<Code slot="preview" code={importedCode} lang="ts" title="src/env.d.ts" /> + +</Preview> + +## `<Code>` Props + +**Implementation:** [`Code.astro`](https://github.com/expressive-code/expressive-code/blob/main/packages/astro-expressive-code/components/Code.astro) + +The `<Code>` component accepts all the props documented in the [Expressive Code “Code Component” docs](https://expressive-code.com/key-features/code-component/#available-props). diff --git a/docs/src/content/docs/components/file-tree.mdx b/docs/src/content/docs/components/file-tree.mdx new file mode 100644 index 00000000..bede1bb1 --- /dev/null +++ b/docs/src/content/docs/components/file-tree.mdx @@ -0,0 +1,225 @@ +--- +title: File Tree +description: Learn how to display the structure of a directory with file icons and collapsible sub-directories in Starlight. +--- + +import { FileTree } from '@astrojs/starlight/components'; + +To display the structure of a directory with file icons and collapsible sub-directories, use the `<FileTree>` component. + +import Preview from '~/components/component-preview.astro'; + +<Preview> + +<FileTree slot="preview"> + +- astro.config.mjs an **important** file +- package.json +- README.md +- src + - components + - **Header.astro** + - … +- pages/ + +</FileTree> + +</Preview> + +## Import + +```tsx +import { FileTree } from '@astrojs/starlight/components'; +``` + +## Usage + +Display a file tree with file icons and collapsible sub-directories using the `<FileTree>` component. + +Specify the structure of your files and directories with an [unordered Markdown list](https://www.markdownguide.org/basic-syntax/#unordered-lists) inside `<FileTree>`. +Create a sub-directory using a nested list or add a `/` to the end of a list item to render it as a directory without specific content. + +<Preview> + +```mdx +import { FileTree } from '@astrojs/starlight/components'; + +<FileTree> + +- astro.config.mjs +- package.json +- src + - components + - Header.astro + - Title.astro + - pages/ + +</FileTree> +``` + +<Fragment slot="markdoc"> + +```markdoc +{% filetree %} +- astro.config.mjs +- package.json +- src + - components + - Header.astro + - Title.astro + - pages/ +{% /filetree %} +``` + +</Fragment> + +<FileTree slot="preview"> + +- astro.config.mjs +- package.json +- src + - components + - Header.astro + - Title.astro + - pages/ + +</FileTree> + +</Preview> + +### Highlight entries + +Make a file or directory stand out by making its name bold, e.g. `**README.md**`. + +<Preview> + +```mdx {7} +import { FileTree } from '@astrojs/starlight/components'; + +<FileTree> + +- src + - components + - **Header.astro** + - Title.astro + +</FileTree> +``` + +<Fragment slot="markdoc"> + +```markdoc {4} +{% filetree %} +- src + - components + - **Header.astro** + - Title.astro +{% /filetree %} +``` + +</Fragment> + +<FileTree slot="preview"> + +- src + - components + - **Header.astro** + - Title.astro + +</FileTree> + +</Preview> + +### Add comments + +Add a comment to a file or directory by adding more text after the name. +Inline Markdown formatting such as bold and italics is supported in comments. + +<Preview> + +```mdx {7} +import { FileTree } from '@astrojs/starlight/components'; + +<FileTree> + +- src + - components + - Header.astro an **important** file + - Title.astro + +</FileTree> +``` + +<Fragment slot="markdoc"> + +```markdoc {4} +{% filetree %} +- src + - components + - Header.astro an **important** file + - Title.astro +{% /filetree %} +``` + +</Fragment> + +<FileTree slot="preview"> + +- src + - components + - Header.astro an **important** file + - Title.astro + +</FileTree> + +</Preview> + +### Add placeholders + +Add placeholder files and directories by using either `...` or `…` as the name. +This can be useful to indicate to a reader that a folder is expected to contain more items without specifying them all explicitly. + +<Preview> + +```mdx {8} +import { FileTree } from '@astrojs/starlight/components'; + +<FileTree> + +- src + - components + - Header.astro + - … + +</FileTree> +``` + +<Fragment slot="markdoc"> + +```markdoc {5} +{% filetree %} +- src + - components + - Header.astro + - … +{% /filetree %} +``` + +</Fragment> + +<FileTree slot="preview"> + +- src + - components + - Header.astro + - … + +</FileTree> + +</Preview> + +## `<FileTree>` Props + +**Implementation:** [`FileTree.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/FileTree.astro) + +The `<FileTree>` component does not accept any props. diff --git a/docs/src/content/docs/components/icons.mdx b/docs/src/content/docs/components/icons.mdx new file mode 100644 index 00000000..73f9d861 --- /dev/null +++ b/docs/src/content/docs/components/icons.mdx @@ -0,0 +1,128 @@ +--- +title: Icons +description: Learn how to display icons in Starlight. +--- + +import { Icon } from '@astrojs/starlight/components'; + +To display icons from Starlight’s [built-in icon set](/reference/icons/#all-icons), use the `<Icon>` component. + +import Preview from '~/components/component-preview.astro'; + +<Preview> + +<Icon + slot="preview" + name="open-book" + color="var(--sl-color-text-accent)" + size="4rem" +/> + +</Preview> + +## Import + +```tsx +import { Icon } from '@astrojs/starlight/components'; +``` + +## Usage + +Display an icon using the `<Icon>` component. +An icon requires a [`name`](#name) set to [one of Starlight’s built-in icons](/reference/icons/#all-icons) and can optionally include a [`label`](#label) to provide context for screen readers. + +<Preview> + +```mdx +import { Icon } from '@astrojs/starlight/components'; + +<Icon name="star" /> +<Icon name="starlight" label="The Starlight logo" /> +``` + +<Fragment slot="markdoc"> + +```markdoc +{% icon name="star" /%} +{% icon name="starlight" label="The Starlight logo" /%} +``` + +</Fragment> + +<Fragment slot="preview"> + <Icon name="star" /> + <Icon name="starlight" label="The Starlight logo" /> +</Fragment> + +</Preview> + +### Customize icons + +The [`size`](#size) and [`color`](#color) attributes can be used to adjust the icon’s appearance using CSS units and color values. +The [`class`](#class) attribute can be used to add custom CSS classes to the icon. + +<Preview> + +```mdx +import { Card } from '@astrojs/starlight/components'; + +<Icon name="star" color="goldenrod" size="2rem" /> +<Icon name="rocket" color="var(--sl-color-text-accent)" /> +``` + +<Fragment slot="markdoc"> + +```markdoc +{% icon name="star" color="goldenrod" size="2rem" /%} +{% icon name="rocket" color="var(--sl-color-text-accent)" /%} +``` + +</Fragment> + +<Fragment slot="preview"> + <Icon name="star" color="goldenrod" size="2rem" /> + <Icon name="rocket" color="var(--sl-color-text-accent)" /> +</Fragment> + +</Preview> + +## `<Icon>` Props + +**Implementation:** [`Icon.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/Icon.astro) + +The `<Icon>` component accepts the following props: + +### `name` + +**required** +**type:** `string` + +The name of the icon to display set to [one of Starlight’s built-in icons](/reference/icons/#all-icons). + +### `label` + +**type:** `string` + +An optional label to provide context for assistive technologies, such as screen readers. + +When `label` is not set, the icon will be completely hidden from assistive technologies. +In this case, make sure the context is still understandable without the icon. +For example, a link containing only the icon **must** include the `label` attribute in order to be accessible, but if a link contains text and the icon is purely decorative, omitting the `label` may make sense. + +### `size` + +**type:** `string` + +The size of the icon using CSS units. + +### `color` + +**type:** `string` + +The color of the icon using a CSS color value. + +### `class` + +**type:** `string` + +Custom CSS classes to add to the icon. diff --git a/docs/src/content/docs/components/link-buttons.mdx b/docs/src/content/docs/components/link-buttons.mdx new file mode 100644 index 00000000..457796c9 --- /dev/null +++ b/docs/src/content/docs/components/link-buttons.mdx @@ -0,0 +1,145 @@ +--- +title: Link Buttons +description: Learn how to create link buttons in Starlight for visually distinct call-to-action links. +--- + +import { LinkButton } from '@astrojs/starlight/components'; + +To display visually distinct call-to-action links, use the `<LinkButton>` component. + +import Preview from '~/components/component-preview.astro'; + +<Preview> + +<LinkButton slot="preview" href="/getting-started/"> + Read the docs +</LinkButton> + +</Preview> + +## Import + +```tsx +import { LinkButton } from '@astrojs/starlight/components'; +``` + +## Usage + +Use the `<LinkButton>` component to display a visually distinct call-to-action link. +A link button is useful for directing users to the most relevant or actionable content and is often used on landing pages. + +A `<LinkButton>` requires an [`href`](#href) attribute. +Optionally, customize the appearance of the link button using the [`variant`](#variant) attribute, which can be set to `primary` (the default), `secondary`, or `minimal`. + +<Preview> + +```mdx +import { LinkButton } from '@astrojs/starlight/components'; + +<LinkButton href="/getting-started/">Get started</LinkButton> +<LinkButton href="/reference/configuration/" variant="secondary"> + Configuration Reference +</LinkButton> +``` + +<Fragment slot="markdoc"> + +```markdoc +{% linkbutton href="/getting-started/" %}Get started{% /linkbutton %} + +{% linkbutton href="/reference/configuration/" variant="secondary" %} +Configuration Reference +{% /linkbutton %} +``` + +</Fragment> + +<Fragment slot="preview"> + <LinkButton href="/getting-started/">Get started</LinkButton> + <LinkButton href="/reference/configuration/" variant="secondary"> + Configuration Reference + </LinkButton> +</Fragment> + +</Preview> + +### Add icons to cards + +Include an icon in a link button using the [`icon`](#icon) attribute set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons). + +The [`iconPlacement`](#iconplacement) attribute can be used to place the icon before the text by setting it to `start` (defaults to `end`). + +<Preview> + +```mdx {6-7} +import { LinkButton } from '@astrojs/starlight/components'; + +<LinkButton + href="https://docs.astro.build" + variant="secondary" + icon="external" + iconPlacement="start" +> + Related: Astro +</LinkButton> +``` + +<Fragment slot="markdoc"> + +```markdoc {4-5} +{% linkbutton + href="https://docs.astro.build" + variant="secondary" + icon="external" + iconPlacement="start" %} +Related: Astro +{% /linkbutton %} +``` + +</Fragment> + +<LinkButton + slot="preview" + href="https://docs.astro.build" + variant="secondary" + icon="external" + iconPlacement="start" +> + Related: Astro +</LinkButton> + +</Preview> + +## `<LinkButton>` Props + +**Implementation:** [`LinkButton.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/LinkButton.astro) + +The `<LinkButton>` component accepts the following props and also any [other `<a>` attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a): + +### `href` + +**required** +**type:** `string` + +The URL that the link button points to. + +### `variant` + +**type:** `'primary' | 'secondary' | 'minimal'` +**default:** `'primary'` + +The appearance of the link button. +Set to `primary` for a prominent call-to-action link using the theme’s accent color, `secondary` for a less prominent link, or `minimal` for a link with minimal styling. + +### `icon` + +**type:** `string` + +A link button can include an `icon` attribute set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons). + +### `iconPlacement` + +**type:** `'start' | 'end'` +**default:** `'end'` + +Determines the placement of the icon in relation to the link button text. diff --git a/docs/src/content/docs/components/link-cards.mdx b/docs/src/content/docs/components/link-cards.mdx new file mode 100644 index 00000000..3cc394ac --- /dev/null +++ b/docs/src/content/docs/components/link-cards.mdx @@ -0,0 +1,125 @@ +--- +title: Link Cards +description: Learn how to display links prominently as cards in Starlight. +sidebar: + order: 3 +--- + +import { LinkCard } from '@astrojs/starlight/components'; + +To display links to different pages prominently, use the `<LinkCard>` component. + +import Preview from '~/components/component-preview.astro'; + +<Preview> + +<LinkCard + slot="preview" + title="Customizing Starlight" + description="Learn how to make your Starlight site your own with custom styles, fonts, and more." + href="/guides/customization/" +/> + +</Preview> + +## Import + +```tsx +import { LinkCard } from '@astrojs/starlight/components'; +``` + +## Usage + +Display a link prominently using the `<LinkCard>` component. +Each `<LinkCard>` requires a [`title`](#title) and an [`href`](#href) attribute. + +<Preview> + +```mdx +import { LinkCard } from '@astrojs/starlight/components'; + +<LinkCard title="Authoring Markdown" href="/guides/authoring-content/" /> +``` + +<Fragment slot="markdoc"> + +```markdoc +{% linkcard title="Authoring Markdown" href="/guides/authoring-content/" /%} +``` + +</Fragment> + +<LinkCard + slot="preview" + title="Authoring Markdown" + href="/guides/authoring-content/" +/> + +</Preview> + +### Add a link description + +Add a short description to a link card using the [`description`](#description) attribute. + +<Preview> + +```mdx {6} +import { LinkCard } from '@astrojs/starlight/components'; + +<LinkCard + title="Internationalization" + href="/guides/i18n/" + description="Configure Starlight to support multiple languages." +/> +``` + +<Fragment slot="markdoc"> + +```markdoc {4} +{% linkcard + title="Internationalization" + href="/guides/i18n/" + description="Configure Starlight to support multiple languages." /%} +``` + +</Fragment> + +<LinkCard + slot="preview" + title="Internationalization" + href="/guides/i18n/" + description="Configure Starlight to support multiple languages." +/> + +</Preview> + +### Group link cards + +Display multiple link cards side-by-side when there’s enough space by grouping them using the [`<CardGrid>`](/components/card-grids/) component. +See the [“Group link cards”](/components/card-grids/#group-link-cards) guide for an example. + +## `<LinkCard>` Props + +**Implementation:** [`LinkCard.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/LinkCard.astro) + +The `<LinkCard>` component accepts the following props, as well as all other [`<a>` element attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a): + +### `title` + +**required** +**type:** `string` + +The title of the link card to display. + +### `href` + +**required** +**type:** `string` + +The URL to link to when the card is interacted with. + +### `description` + +**type:** `string` + +An optional description to display below the title. diff --git a/docs/src/content/docs/components/steps.mdx b/docs/src/content/docs/components/steps.mdx new file mode 100644 index 00000000..4f30b7ff --- /dev/null +++ b/docs/src/content/docs/components/steps.mdx @@ -0,0 +1,120 @@ +--- +title: Steps +description: Learn how to style numbered lists of tasks to create step-by-step guides in Starlight. +--- + +import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; + +To style a numbered list of tasks to create step-by-step guides, use the `<Steps>` component. + +import Preview from '~/components/component-preview.astro'; + +<Preview> + +<Steps slot="preview"> + +1. Create a new Starlight project: + + <Tabs syncKey="pkg"> + + <TabItem label="npm"> + + ```sh + npm create astro@latest -- --template starlight + ``` + + </TabItem> + + <TabItem label="pnpm"> + + ```sh + pnpm create astro --template starlight + ``` + + </TabItem> + + <TabItem label="Yarn"> + + ```sh + yarn create astro --template starlight + ``` + + </TabItem> + + </Tabs> + +2. Write your first documentation page. + +</Steps> + +</Preview> + +## Import + +```tsx +import { Steps } from '@astrojs/starlight/components'; +``` + +## Usage + +Use the `<Steps>` component to style numbered lists of tasks. +This is useful for more complex step-by-step guides where each step needs to be clearly highlighted. + +Wrap `<Steps>` around a standard Markdown ordered list. +All the usual Markdown syntax is applicable inside `<Steps>`. + +<Preview> + +````mdx +import { Steps } from '@astrojs/starlight/components'; + +<Steps> + +1. Import the component into your MDX file: + + ```js + import { Steps } from '@astrojs/starlight/components'; + ``` + +2. Wrap `<Steps>` around your ordered list items. + +</Steps> +```` + +<Fragment slot="markdoc"> + +````markdoc +{% steps %} + +1. Import the component into your MDX file: + + ```js + import { Steps } from '@astrojs/starlight/components'; + ``` + +2. Wrap `<Steps>` around your ordered list items. + +{% /steps %} +```` + +</Fragment> + +<Steps slot="preview"> + +1. Import the component into your MDX file: + + ```js + import { Steps } from '@astrojs/starlight/components'; + ``` + +2. Wrap `<Steps>` around your ordered list items. + +</Steps> + +</Preview> + +## `<Steps>` Props + +**Implementation:** [`Steps.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/Steps.astro) + +The `<Steps>` component does not accept any props. diff --git a/docs/src/content/docs/components/tabs.mdx b/docs/src/content/docs/components/tabs.mdx new file mode 100644 index 00000000..c530e2c8 --- /dev/null +++ b/docs/src/content/docs/components/tabs.mdx @@ -0,0 +1,221 @@ +--- +title: Tabs +description: Learn how to create tabbed interfaces in Starlight to group equivalent information. +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +To create a tabbed interface use the `<Tabs>` and `<TabItem>` components. +Tabs are useful for grouping equivalent information where a user only needs to see one of several options. + +import Preview from '~/components/component-preview.astro'; + +<Preview> + +<Tabs slot="preview"> + <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem> + <TabItem label="Moons">Io, Europa, Ganymede</TabItem> +</Tabs> + +</Preview> + +## Import + +```tsx +import { Tabs, TabItem } from '@astrojs/starlight/components'; +``` + +## Usage + +Display a tabbed interface using the `<Tabs>` and `<TabItem>` components. +Each `<TabItem>` must have a [`label`](#label) to display to users. + +<Preview> + +```mdx +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +<Tabs> + <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem> + <TabItem label="Moons">Io, Europa, Ganymede</TabItem> +</Tabs> +``` + +<Fragment slot="markdoc"> + +```markdoc +{% tabs %} +{% tabitem label="Stars" %} +Sirius, Vega, Betelgeuse +{% /tabitem %} + +{% tabitem label="Moons" %} +Io, Europa, Ganymede +{% /tabitem %} +{% /tabs %} +``` + +</Fragment> + +<Tabs slot="preview"> + <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem> + <TabItem label="Moons">Io, Europa, Ganymede</TabItem> +</Tabs> + +</Preview> + +### Sync tabs + +Keep multiple tab groups synchronized by adding the [`syncKey`](#synckey) attribute. + +All `<Tabs>` on a page with the same `syncKey` value will display the same active label. +This allows your reader to choose once (e.g. their operating system or package manager), and see their choice persisted across page navigations. + +To synchronize related tabs, add an identical `syncKey` property to each `<Tabs>` component and ensure that they all use the same `<TabItem>` labels: + +<Preview> + +```mdx 'syncKey="constellations"' +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +_Some stars:_ + +<Tabs syncKey="constellations"> + <TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem> + <TabItem label="Gemini">Pollux, Castor A, Castor B</TabItem> +</Tabs> + +_Some exoplanets:_ + +<Tabs syncKey="constellations"> + <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> + <TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem> +</Tabs> +``` + +<Fragment slot="markdoc"> + +```markdoc 'syncKey="constellations"' +_Some stars:_ + +{% tabs syncKey="constellations" %} +{% tabitem label="Orion" %} +Bellatrix, Rigel, Betelgeuse +{% /tabitem %} + +{% tabitem label="Gemini" %} +Pollux, Castor A, Castor B +{% /tabitem %} +{% /tabs %} + +_Some exoplanets:_ + +{% tabs syncKey="constellations" %} +{% tabitem label="Orion" %} +HD 34445 b, Gliese 179 b, Wasp-82 b +{% /tabitem %} + +{% tabitem label="Gemini" %} +Pollux b, HAT-P-24b, HD 50554 b +{% /tabitem %} +{% /tabs %} +``` + +</Fragment> + +<Fragment slot="preview"> + +_Some stars:_ + +<Tabs syncKey="constellations"> + <TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem> + <TabItem label="Gemini">Pollux, Castor A, Castor B</TabItem> +</Tabs> + +_Some exoplanets:_ + +<Tabs syncKey="constellations"> + <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> + <TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem> +</Tabs> + +</Fragment> + +</Preview> + +### Add icons to tabs + +Include an icon in a tab item using the [`icon`](#icon) attribute set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons) to display an icon next to the label. + +<Preview> + +```mdx /icon="\w+"/ +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +<Tabs> + <TabItem label="Stars" icon="star"> + Sirius, Vega, Betelgeuse + </TabItem> + <TabItem label="Moons" icon="moon"> + Io, Europa, Ganymede + </TabItem> +</Tabs> +``` + +<Fragment slot="markdoc"> + +```markdoc /icon="\w+"/ +{% tabs %} +{% tabitem label="Stars" icon="star" %} +Sirius, Vega, Betelgeuse +{% /tabitem %} + +{% tabitem label="Moons" icon="moon" %} +Io, Europa, Ganymede +{% /tabitem %} +{% /tabs %} +``` + +</Fragment> + +<Tabs slot="preview"> + <TabItem label="Stars" icon="star"> + Sirius, Vega, Betelgeuse + </TabItem> + <TabItem label="Moons" icon="moon"> + Io, Europa, Ganymede + </TabItem> +</Tabs> + +</Preview> + +## `<Tabs>` Props + +**Implementation:** [`Tabs.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/Tabs.astro) + +The `<Tabs>` component groups multiple `<TabItem>` components together and accepts the following props: + +### `syncKey` + +**type:** `string` + +A key used to keep multiple tab groups synchronized across multiple pages. + +## `<TabItem>` Props + +**Implementation:** [`TabItem.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/user-components/TabItem.astro) + +A set of tabs is composed of tab items, each with the following props: + +### `label` + +**required** +**type:** `string` + +A tab item must include a `label` attribute set to the text that will be displayed in the tab. + +### `icon` + +**type:** `string` + +Each tab item can include an `icon` attribute set to the name of [one of Starlight’s built-in icons](/reference/icons/#all-icons) to display an icon next to the label. diff --git a/docs/src/content/docs/components/using-components.mdx b/docs/src/content/docs/components/using-components.mdx new file mode 100644 index 00000000..2a3d2f2c --- /dev/null +++ b/docs/src/content/docs/components/using-components.mdx @@ -0,0 +1,94 @@ +--- +title: Using components +description: Using components in MDX and Markdoc with Starlight. +sidebar: + order: 1 +--- + +Components let you easily reuse a piece of UI or styling consistently. +Examples might include a link card or a YouTube embed. +Starlight supports the use of components in [MDX](https://mdxjs.com/) and [Markdoc](https://markdoc.dev/) files and provides some common components for you to use. + +[Learn more about building components in the Astro Docs](https://docs.astro.build/en/core-concepts/astro-components/). + +## Using a component in MDX + +You can use a component by importing it into your MDX file and then rendering it as a JSX tag. +These look like HTML tags but start with an uppercase letter matching the name in your `import` statement: + +```mdx +--- +# src/content/docs/example.mdx +title: Welcome to my docs +--- + +import { Icon } from '@astrojs/starlight/components'; +import CustomCard from '../../components/CustomCard.astro'; + +<Icon name="open-book" /> + +<CustomCard>Components can also contain **nested content**.</CustomCard> +``` + +Because Starlight is powered by Astro, you can add support for components built with any [supported UI framework (React, Preact, Svelte, Vue, Solid, and Alpine)](https://docs.astro.build/en/core-concepts/framework-components/) in your MDX files. +Learn more about [using components in MDX](https://docs.astro.build/en/guides/markdown-content/#using-components-in-mdx) in the Astro docs. + +## Using a component in Markdoc + +Add support for authoring content in Markdoc by following our [Markdoc set-up guide](/guides/authoring-content/#markdoc). + +Using the Starlight Markdoc preset, you can use Starlight’s built-in components with Markdoc’s `{% %}` tag syntax. +Unlike MDX, components in Markdoc do not need to be imported. +The following example renders Starlight’s [card component](/components/cards/) in a Markdoc file: + +```markdoc +--- +# src/content/docs/example.mdoc +title: Welcome to my docs +--- + +{% card title="Stars" icon="star" %} +Sirius, Vega, Betelgeuse +{% /card %} +``` + +See the [Astro Markdoc integration documentation](https://docs.astro.build/en/guides/integrations-guide/markdoc/#render-components) for more information on how to use components in Markdoc files. + +## Built-in components + +Starlight provides built-in components for common documentation use cases. +These components are available from the `@astrojs/starlight/components` package in MDX files and from the [Starlight Markdoc preset](/guides/authoring-content/#markdoc) in Markdoc files. + +See the sidebar for a list of available components and how to use them. + +## Compatibility with Starlight’s styles + +Starlight applies default styling to your Markdown content, for example, adding margin between elements. +If these styles conflict with your component’s appearance, set the `not-content` class on your component to disable them. + +```astro 'class="not-content"' +--- +// src/components/Example.astro +--- + +<div class="not-content"> + <p>Not impacted by Starlight’s default content styling.</p> +</div> +``` + +## Component props + +Use the [`ComponentProps`](https://docs.astro.build/en/guides/typescript/#componentprops-type) type from `astro/types` to reference the `Props` accepted by a component even if they are not exported by the component itself. +This can be helpful when wrapping or extending an existing component. + +The following example uses `ComponentProps` to get the type of the props accepted by Starlight’s built-in `Icon` component: + +```astro +--- +// src/components/Example.astro +import type { ComponentProps } from 'astro/types'; +import { Icon } from '@astrojs/starlight/icon'; + +type IconProps = ComponentProps<typeof Icon>; +--- +``` diff --git a/docs/src/content/docs/de/guides/components.mdx b/docs/src/content/docs/de/guides/components.mdx deleted file mode 100644 index 8db24999..00000000 --- a/docs/src/content/docs/de/guides/components.mdx +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: Komponenten -description: Verwendung von Komponenten in MDX mit Starlight. ---- - -Mit Komponenten kannst du auf einfache Weise einen Teil der Benutzeroberfläche oder ein Styling konsistent wiederverwenden, -zum Beispiel eine Linkkarte oder eine YouTube-Einbettung. -Starlight unterstützt die Verwendung von Komponenten in [MDX](https://mdxjs.com/)-Dateien und stellt dir einige gängige Komponenten zur Verfügung, die du verwenden kannst. - -[Erfahre mehr über die Erstellung von Komponenten in den Astro Docs](https://docs.astro.build/de/core-concepts/astro-components/). - -## Verwendung einer Komponente - -Du kannst eine Komponente verwenden, indem du sie in deine MDX-Datei importierst und sie dann als JSX-Tag renders. -Diese sehen wie HTML-Tags aus, beginnen aber mit einem Großbuchstaben, der dem Namen in der `import`-Anweisung entspricht: - -```mdx ---- -# src/content/docs/index.mdx -title: Willkommen bei meiner Dokumentation ---- - -import SomeComponent from '~/components/SomeComponent.astro'; -import AnotherComponent from '~/components/AnotherComponent.astro'; - -<SomeComponent prop="something" /> - -<AnotherComponent> - Komponenten können auch **verschachtelten Inhalt** enthalten. -</AnotherComponent> -``` - -Da Starlight auf Astro basiert, kannst du Komponenten, die mit einem beliebigen [unterstützten UI-Framework (React, Preact, Svelte, Vue, Solid, Lit und Alpine)](https://docs.astro.build/de/core-concepts/framework-components/) erstellt wurden, in deine MDX-Dateien aufnehmen. -Erfahre mehr über [Verwendung von Komponenten in MDX](https://docs.astro.build/de/guides/markdown-content/#using-components-in-mdx) in den Astro-Dokumenten. - -### Kompatibilität mit Starlights Stilen - -Starlight wendet Standardstile auf deinen Markdown-Inhalten an, zum Beispiel das Hinzufügen von Abständen zwischen Elementen. -Wenn diese Stile mit dem Erscheinungsbild deiner Komponente in Konflikt stehen, setze die Klasse `not-content` auf deine Komponente, um sie zu deaktivieren. - -```astro ---- -// src/components/Beispiel.astro ---- - -<div class="not-content"> - <p>Not impacted by Starlight’s default content styling.</p> -</div> -``` - -## Eingebaute Komponenten - -Starlight bietet einige standardmäßig eingebaute Komponenten für gängige Dokumentationszwecke. -Diese Komponenten sind aus dem Paket `@astrojs/starlight/components` verfügbar. - -### Registerkarten - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -Mit den Komponenten `<Tabs>` und `<TabItem>` kannst du eine Oberfläche mit Registerkarten anzeigen. -Jedes `<TabItem>` muss ein `label` haben, welches dem Benutzer angezeigt wird. - -```mdx -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="Sterne">Sirius, Wega, Betelgeuse</TabItem> - <TabItem label="Monde">Io, Europa, Ganymed</TabItem> -</Tabs> -``` - -Der obige Code erzeugt die folgenden Registerkarten auf der Seite: - -<Tabs> - <TabItem label="Sterne">Sirius, Wega, Betelgeuse</TabItem> - <TabItem label="Monde">Io, Europa, Ganymed</TabItem> -</Tabs> - -### Karten - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -Mit der Komponente `<Card>` kannst du Inhalte in einer Box darstellen, die den Stilen von Starlight entspricht. -Packe mehrere Karten in die `<CardGrid>` Komponente ein, um Karten nebeneinander darzustellen, wenn genügend Platz vorhanden ist. - -Eine `<Card>` benötigt einen `title` und kann optional ein `icon` Attribut enthalten, welches auf den Namen [eines von Starlights eingebauten Icons](#alle-icons) gesetzt ist. - -```mdx -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="Schau mal hier"> - Interessanter Inhalt, den du hervorheben möchtest. -</Card> - -<CardGrid> - <Card title="Sterne" icon="star"> - Sirius, Wega, Betelgeuse - </Card> - <Card title="Monde" icon="moon"> - Io, Europa, Ganymed - </Card> -</CardGrid> -``` - -Der obige Code erzeugt folgendes auf der Seite: - -<Card title="Schau mal hier"> - Interessanter Inhalt, den du hervorheben möchtest. -</Card> - -<CardGrid> - <Card title="Sterne" icon="star"> - Sirius, Wega, Betelgeuse - </Card> - <Card title="Monde" icon="moon"> - Io, Europa, Ganymed - </Card> -</CardGrid> - -:::tip[Tipp] -Verwende ein Kartengitter auf deiner Homepage, um die wichtigsten Merkmale deines Projekts darzustellen. -Füge das Attribut `stagger` hinzu, um die zweite Spalte der Karten vertikal zu verschieben und visuell interessant zu gestalten: - -```astro -<CardGrid stagger> - <!-- Karten --> -</CardGrid> -``` - -::: - -### Link Cards - -Verwende die `<LinkCard>` Komponente, um auffallend auf verschiedene Seiten zu verlinken. - -Eine `<LinkCard>` benötigt ein `title` und ein [`href`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href) Attribut. Du kannst optional eine kurze `description` oder andere Link-Attribute wie `target` einfügen. - -Gruppiere mehrere `<LinkCard>`-Komponenten in `<CardGrid>`, um Karten nebeneinander anzuzeigen, wenn genügend Platz vorhanden ist. - -```mdx -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -<LinkCard - title="Starlight anpassen" - description="Finde heraus, wie du deine Starlight-Site mit eigenen Stilen, Schriftarten und mehr anpassen können." - href="/de/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Erstellung von Markdown" - href="/de/guides/authoring-content/" - /> - <LinkCard title="Komponenten" href="/de/guides/components/" /> -</CardGrid> -``` - -Der obige Code erzeugt folgendes auf der Seite: - -import { LinkCard } from '@astrojs/starlight/components'; - -<LinkCard - title="Starlight anpassen" - description="Finde heraus, wie du deine Starlight-Site mit eigenen Stilen, Schriftarten und mehr anpassen können." - href="/de/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Erstellung von Markdown" - href="/de/guides/authoring-content/" - /> - <LinkCard title="Komponenten" href="/de/guides/components/" /> -</CardGrid> - -### Icon - -import { Icon } from '@astrojs/starlight/components'; -import IconsList from '~/components/icons-list.astro'; - -Starlight stellt eine Reihe von allgemeinen Icons zur Verfügung, die du mit der Komponente `<Icon>` in deinem Inhalt anzeigen kannst. - -Jedes `<Icon>` benötigt einen [`name`](#alle-icons) und kann optional ein `label`, `size` und `color` Attribut enthalten. - -```mdx -import { Icon } from '@astrojs/starlight/components'; - -<Icon name="star" color="goldenrod" size="2rem" /> -``` - -Der obige Code erzeugt folgendes auf der Seite: - -<Icon name="star" color="goldenrod" size="2rem" /> - -#### Alle Icons - -Nachfolgend findest du eine Liste aller verfügbaren Icons mit den dazugehörigen Namen. Klicke auf ein Symbol, um den Komponentencode dafür zu kopieren. - -<IconsList /> diff --git a/docs/src/content/docs/es/getting-started.mdx b/docs/src/content/docs/es/getting-started.mdx index 5ac0e335..a8c44dae 100644 --- a/docs/src/content/docs/es/getting-started.mdx +++ b/docs/src/content/docs/es/getting-started.mdx @@ -91,7 +91,7 @@ Lee más sobre el enrutamiento basado en archivos y el soporte para archivos MDX - **Configura:** Aprende acerca de las opciones comunes en [“Personalizando Starlight”](/es/guides/customization/). - **Navega:** Configura tu barra lateral siguiendo la guía [“Barra Lateral de Navegación”](/es/guides/sidebar/). -- **Componentes:** Descubre tarjetas incorporadas, pestañas y más en la guía [“Componentes”](/es/guides/components/). +- **Componentes:** Descubre tarjetas incorporadas, pestañas y más en la guía [“Componentes”](/es/components/using-components/). - **Despliega:** Publica tu trabajo siguiendo la guía [“Despliega tu sitio”](https://docs.astro.build/es/guides/deploy/) en la documentación de Astro. ## Actualizando Starlight diff --git a/docs/src/content/docs/es/guides/components.mdx b/docs/src/content/docs/es/guides/components.mdx deleted file mode 100644 index 99c4ede6..00000000 --- a/docs/src/content/docs/es/guides/components.mdx +++ /dev/null @@ -1,507 +0,0 @@ ---- -title: Componentes -description: Utilizando componentes en MDX con Starlight. ---- - -Los componentes te permiten reutilizar fácilmente una parte de la interfaz de usuario o un estilo de manera consistente. Ejemplos podrían incluir una tarjeta de enlace o un incrustado de YouTube. Starlight admite el uso de componentes en archivos [MDX](https://mdxjs.com/) y proporciona algunos componentes comunes para que los utilices. - -[Aprende más sobre la construcción de componentes en los docs de Astro](https://docs.astro.build/en/core-concepts/astro-components/). - -## Usando un componente - -Puedes utilizar un componente importándolo en tu archivo MDX y luego renderizándolo como una etiqueta JSX. Estas etiquetas se ven como etiquetas HTML, pero comienzan con una letra mayúscula que coincide con el nombre en tu declaración de `import`: - -```mdx ---- -# src/content/docs/example.mdx -title: Bienvenido a mis docs ---- - -import UnComponente from '../../componentes/UnComponente.astro'; -import OtroComponente from '../../componentes/OtroComponente.astro'; - -<UnComponente prop="algo" /> - -<OtroComponente> - Los componentes también pueden contener **contenido anidado**. -</OtroComponente> -``` - -Debido a que Starlight está impulsado por Astro, puedes agregar soporte para componentes construidos con cualquier [framework UI compatible (React, Preact, Svelte, Vue, Solid, Lit y Alpine)](https://docs.astro.build/en/core-concepts/framework-components/) en tus archivos MDX. - -### Compatibilidad con los estilos de Starlight - -Starlight aplica estilos predeterminados a tu contenido en Markdown, por ejemplo, añadiendo margen entre elementos. -Si estos estilos entran en conflicto con la apariencia de tu componente, establece la clase `not-content` en tu componente para deshabilitarlos. - -```astro 'class="not-content"' ---- -// src/components/Ejemplo.astro ---- - -<div class="not-content"> - <p> - No se ve afectado por el estilo de contenido predeterminado de Starlight. - </p> -</div> -``` - -## Componentes integrados - -Starlight proporciona algunos componentes integrados para casos de uso comunes en la documentación. Estos componentes están disponibles en el paquete `@astrojs/starlight/components`. - -### Pestañas - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -Puedes mostrar una interfaz con pestañas utilizando los componentes `<Tabs>` y `<TabItem>`. -Cada `<TabItem>` debe tener una `label` que se mostrará a los usuarios. -Usa el atributo opcional `icon` para incluir uno de los [iconos integrados de Starlight](#todos-los-iconos) junto a la etiqueta. - -```mdx -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="Estrellas" icon="star"> - Sirius, Vega, Betelgeuse - </TabItem> - <TabItem label="Lunas" icon="moon"> - Io, Europa, Ganymede - </TabItem> -</Tabs> -``` - -El código anterior genera las siguientes pestañas en la página: - -<Tabs> - <TabItem label="Estrellas" icon="star"> - Sirius, Vega, Betelgeuse - </TabItem> - <TabItem label="Lunas" icon="moon"> - Io, Europa, Ganymede - </TabItem> -</Tabs> - -#### Pestañas sincronizadas - -Manten varias pestañas sincronizadas añadiendo el atributo `syncKey`. - -Todas las `<Tabs>` en una página con el mismo valor de `syncKey` mostrarán la misma etiqueta activa. Esto permite a tu lector elegir una vez (por ejemplo, su sistema operativo o gestor de paquetes) y ver su elección persistida en toda la navegación de la página. - -Para sincronizar pestañas relacionadas, añade una propiedad `syncKey` idéntica a cada componente `<Tabs>` y asegúrate de que todos usen las mismas etiquetas `<TabItem>`: - -```mdx 'syncKey="constellations"' -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -_Algunas estrellas:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem> - <TabItem label="Gemini">Pollux, Cástor A, Cástor B</TabItem> -</Tabs> - -_Algunos exoplanetas:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> -``` - -El código anterior genera lo siguiente en la página: - -_Algunas estrellas:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem> - <TabItem label="Gemini">Pollux, Cástor A, Cástor B</TabItem> -</Tabs> - -_Algunos exoplanetas:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> - -### Tarjetas - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -Puedes mostrar contenido en una caja que coincida con los estilos de Starlight utilizando el componente `<Card>`. Envuelve varias tarjetas en el componente `<CardGrid>` para mostrar las tarjetas una al lado de la otra cuando hay suficiente espacio. - -El componente `<Card>` requiere un `title` y opcionalmente puede incluir un atributo `icon` establecido con el nombre de [uno de los iconos integrados de Starlight](#todos-los-iconos). - -```mdx -# src/content/docs/example.mdx - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="¡Echa un vistazo a esto!"> - Contenido interesante que quieres resaltar. -</Card> - -<CardGrid> - <Card title="Estrellas" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Lunas" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> -``` - -El código anterior genera lo siguiente en la página: - -<Card title="¡Echa un vistazo a esto!"> - Contenido interesante que quieres resaltar. -</Card> - -<CardGrid> - <Card title="Estrellas" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Lunas" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> - -:::tip -Utiliza una cuadrícula de tarjetas en tu página de inicio para mostrar las características clave de tu proyecto. Agrega el atributo `stagger` para desplazar verticalmente la segunda columna de tarjetas y agregar interés visual: - -```astro -<CardGrid stagger> - <!-- tarjetas --> -</CardGrid> -``` - -::: - -### Tarjetas de enlace - -Usa el componente `<LinkCard>` para vincular de forma prominente a diferentes páginas. - -Un `<LinkCard>` requiere un `title` y un atributo [`href`](https://developer.mozilla.org/es/docs/Web/HTML/Element/a#href). Opcionalmente puedes incluir una breve `description` u otros atributos de enlace como `target`. - -Agrupa varios componentes `<LinkCard>` en `<CardGrid>` para mostrar las tarjetas una al lado de la otra cuando hay suficiente espacio. - -```mdx -# src/content/docs/example.mdx - -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -<LinkCard - title="Personalizando Starlight" - description="Aprende a hacer que tu sitio Starlight sea único con estilos personalizados, fuentes y más." - href="/es/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Creación de contenido en Markdown" - href="/es/guides/authoring-content/" - /> - <LinkCard title="Componentes" href="/es/guides/components/" /> -</CardGrid> -``` - -El código anterior genera lo siguiente en la página: - -import { LinkCard } from '@astrojs/starlight/components'; - -<LinkCard - title="Personalizando Starlight" - description="Aprende a hacer que tu sitio Starlight sea único con estilos personalizados, fuentes y más." - href="/es/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Creación de contenido en Markdown" - href="/es/guides/authoring-content/" - /> - <LinkCard title="Componentes" href="/es/guides/components/" /> -</CardGrid> - -### Botones de enlace - -Usa el componente `<LinkButton>` para enlaces de llamada a la acción visualmente distintos. -Un botón de enlace es útil para dirigir a los usuarios al contenido más relevante o contenido accionable y se usa a menudo en páginas de destino - -Un `<LinkButton>` requiere un atributo [`href`](https://developer.mozilla.org/es/docs/Web/HTML/Element/a#href) y opcionalmente acepta otros atributos de enlace como `target`. - -El atributo `icon` se puede establecer opcionalmente en el nombre de [uno de los iconos integrados de Starlight](#todos-los-iconos) para incluir un icono junto al texto. -El atributo ìconPlacemente`se puede usar para colocar el icono antes del texto estableciéndolo en`start`(el valor predeterminado es`end`). - -Personaliza la apariencia del botón de enlace utilizando el atributo `variant`, que se puede establecer en `primary` (el valor predeterminado), `secondary` o `minimal`. - -```mdx -# src/content/docs/example.mdx - -import { LinkButton } from '@astrojs/starlight/components'; - -<LinkButton href="/es/getting-started/">Comienza</LinkButton> -<LinkButton href="https://docs.astro.build" variant="secondary" icon="external"> - Relacionado: Astro -</LinkButton> -``` - -El código anterior genera lo siguiente en la página: - -import { LinkButton } from '@astrojs/starlight/components'; - -<LinkButton href="/es/getting-started/">Comienza</LinkButton> -<LinkButton href="https://docs.astro.build" variant="secondary" icon="external"> - Relacionado: Astro -</LinkButton> - -### Apartados - -Los apartados son útiles para mostrar información secundaria junto al contenido principal de una página. - -Un `<Aside>` puede tener un `type` opcional de `note` (el valor predeterminado), `tip`, `caution` o `danger`. Establecer un atributo `title` anula el título predeterminado del apartado. - -````mdx -# src/content/docs/example.mdx - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>Un apartado predeterminado sin un título personalizado.</Aside> - -<Aside type="caution" title="Watch out!"> - Un apartado de advertencia *con* un título personalizado. -</Aside> - -<Aside type="tip"> - -Otro contenido también es compatible en los apartados. - -```js -// Una muestra de código, por ejemplo. -``` - -</Aside> - -<Aside type="danger">No le des tu contraseña a nadie.</Aside> -```` - -El código anterior genera lo siguiente en la página: - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>Un apartado predeterminado sin un título personalizado.</Aside> - -<Aside type="caution" title="Watch out!"> - Un apartado de advertencia *con* un título personalizado. -</Aside> - -<Aside type="tip"> - -Otro contenido también es compatible en los apartados. - -```js -// Una muestra de código, por ejemplo. -``` - -</Aside> - -<Aside type="danger">No le des tu contraseña a nadie.</Aside> - -Starlight también proporciona una sintaxis personalizada para renderizar apartados en Markdown y MDX como una alternativa al componente `<Aside>`. -Consulta la guía [“Creación de contenido en Markdown”](/es/guides/authoring-content/#apartados) para obtener más detalles de la sintaxis personalizada. - -### Código - -Usa el componente `<Code>` para renderizar código con resaltado de sintaxis cuando no sea posible usar un [bloque de código Markdown](/es/guides/authoring-content/#bloques-de-código), por ejemplo, para renderizar datos provenientes de fuentes externas como archivos, bases de datos o APIs. - -Consulta el [componente de código de Expressive Code](https://expressive-code.com/key-features/code-component/) para obtener detalles completos de las props que admite `<Code>`. - -```mdx -# src/content/docs/example.mdx - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('¡Esto podría venir de un archivo o CMS!');`; -export const fileName = 'example.js'; -export const highlights = ['file', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> -``` - -El código anterior genera lo siguiente en la página: - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('¡Esto podría venir de un archivo o CMS!');`; -export const fileName = 'example.js'; -export const highlights = ['file', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> - -#### Código importado - -Usa [el sufijo de importación `?raw` de Vite](https://vitejs.dev/guide/assets#importing-asset-as-string) para importar cualquier archivo de código como un string. -Puedes pasar luego este string importado al componente `<Code>` para incluirlo en tu página. - -```mdx title="src/content/docs/example.mdx" "?raw" -import { Code } from '@astrojs/starlight/components'; -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> -``` - -El código anterior genera lo siguiente en la página: - -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> - -### Árbol de archivos - -Usa el componente `<FileTree>` para mostrar la estructura de un directorio con iconos de archivo y subdirectorios colapsables. - -Especifica la estructura de tus archivos y directorios con una [lista Markdown desordenada](https://www.markdownguide.org/basic-syntax/#unordered-lists) dentro de `<FileTree>`. -Crea un subdirectorio usando una lista anidada o agrega un `/` al final de un elemento de la lista para renderizarlo como un directorio sin contenido específico. - -La siguiente sintaxis se puede utilizar para personalizar la apariencia del árbol de archivos: - -- Resalta un archivo o directorio haciendo que su nombre esté en negrita, por ejemplo, `**README.md**`. -- Agrega un comentario a un archivo o directorio añadiendo más texto después del nombre. -- Agrega archivos de marcadores de posición y directorios mediante el uso de `...` o `…` como nombre. - -```mdx -# src/content/docs/example.mdx - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs un archivo **importante** -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> -``` - -El código anterior genera lo siguiente en la página: - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs un archivo **importante** -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> - -### Pasos - -Usa el componente `<Steps>` para dar estilo a listas numeradas de tareas. -Este es útil para guías paso a paso más complejas donde cada paso debe destacarse claramente. - -Envuelve `<Steps>` alrededor de una lista ordenada de Markdown estándar. -Toda la sintaxis de Markdown habitual es aplicable dentro de `<Steps>`. - -````mdx title="src/content/docs/example.mdx" -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Importa el componente en tu archivo MDX: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Envuelve `<Steps>` alrededor de tus elementos de lista ordenada. - -</Steps> -```` - -El código anterior genera lo siguiente en la página: - -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Importa el componente en tu archivo MDX: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Envuelve `<Steps>` alrededor de tus elementos de lista ordenada. - -</Steps> - -### Insignias - -import { Badge } from '@astrojs/starlight/components'; - -Usa el componente `<Badge>` para mostrar pequeñas piezas de información, como estado o etiquetas. - -Pasa el contenido que deseas mostrar al atributo `text` del componente `<Badge>`. - -Por defecto, la insignia usará el color de acento del tema de tu sitio. Para usar un color de insignia integrado, establece el atributo `variant` en uno de los siguientes valores: `note` (azul), `tip` (morado), `danger` (rojo), `caution` (naranja) o `success` (verde). - -El atributo `size` (por defecto: `small`) controla el tamaño del texto de la insignia. `medium` y `large` también son opciones disponibles para mostrar una insignia más grande. - -Para personalizaciones adicionales, utiliza otros atributos de `<span>` como `class` o `style` con CSS personalizado. - -```mdx title="src/content/docs/example.mdx" -import { Badge } from '@astrojs/starlight/components'; - -<Badge text="Nuevo" variant="tip" size="small" /> -<Badge text="Obsoleto" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Personalizado" variant="success" style={{ fontStyle: 'italic' }} /> -``` - -El código anterior genera lo siguiente en la página: - -<Badge text="Nuevo" variant="tip" size="small" /> -<Badge text="Obsoleto" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Personalizado" variant="success" style={{ fontStyle: 'italic' }} /> - -### Iconos - -import { Icon } from '@astrojs/starlight/components'; -import IconsList from '~/components/icons-list.astro'; - -Starlight proporciona un conjunto de iconos comunes que puedes mostrar en tu contenido utilizando el componente `<Icon>`. - -Cada `<Icon>` requiere un atributo `name` que se puede encontrar en la lista de [todos los iconos](#todos-los-iconos), y opcionalmente puede incluir atributos como `label`, `size` y `color`. - -```mdx -# src/content/docs/example.mdx - -import { Icon } from '@astrojs/starlight/components'; - -<Icon name="star" color="goldenrod" size="2rem" /> -``` - -El código anterior genera lo siguiente en la página: - -<Icon name="star" color="goldenrod" size="2rem" /> - -#### Todos los iconos - -A continuación se muestra una lista de todos los iconos disponibles con sus nombres asociados. Haz clic en un ícono para copiar el código del componente correspondiente. - -<IconsList /> diff --git a/docs/src/content/docs/fr/getting-started.mdx b/docs/src/content/docs/fr/getting-started.mdx index 7c00093b..a0856292 100644 --- a/docs/src/content/docs/fr/getting-started.mdx +++ b/docs/src/content/docs/fr/getting-started.mdx @@ -91,7 +91,7 @@ Pour en savoir plus sur le routage par fichier et la prise en charge des fichier - **Configurer :** Découvrez les options courantes dans [« Personnaliser Starlight »](/fr/guides/customization/). - **Naviguer :** Configurez votre barre latérale avec le guide [« Barre latérale de navigation »](/fr/guides/sidebar/). -- **Composants :** Découvrez les cartes, les onglets et d'autres composants intégrés dans le guide [« Composants »](/fr/guides/components/). +- **Composants :** Découvrez les cartes, les onglets et d'autres composants intégrés dans le guide [« Composants »](/fr/components/using-components/). - **Déployer :** Publiez votre travail avec le guide [« Déployer votre site »](https://docs.astro.build/fr/guides/deploy/) dans la documentation d'Astro. ## Mettre à jour Starlight diff --git a/docs/src/content/docs/fr/guides/components.mdx b/docs/src/content/docs/fr/guides/components.mdx deleted file mode 100644 index e37911e6..00000000 --- a/docs/src/content/docs/fr/guides/components.mdx +++ /dev/null @@ -1,515 +0,0 @@ ---- -title: Composants -description: Utilisation de composants dans MDX avec Starlight. ---- - -Les composants vous permettent de réutiliser facilement un élément d'interface utilisateur ou de style de manière cohérente. -Il peut s'agir par exemple d'une carte de lien ou d'une intégration YouTube. -Starlight prend en charge l'utilisation de composants dans les fichiers [MDX](https://mdxjs.com/) et fournit des composants courants que vous pouvez utiliser. - -[Pour en savoir plus sur la création de composants, consultez les Astro Docs](https://docs.astro.build/fr/core-concepts/astro-components/). - -## Utilisation d'un composant - -Vous pouvez utiliser un composant en l'important dans votre fichier MDX et en le rendant sous forme de balise JSX. -Ces balises ressemblent à des balises HTML, mais commencent par une lettre majuscule correspondant au nom de votre déclaration `import` : - -```mdx ---- -# src/content/docs/exemple.mdx -title: Bienvenue dans ma documentation ---- - -import SomeComponent from '../../components/SomeComponent.astro'; -import AnotherComponent from '../../components/AnotherComponent.astro'; - -<SomeComponent prop="something" /> - -<AnotherComponent> - Les composants peuvent également contenir du **contenu imbriqué**. -</AnotherComponent> -``` - -Starlight étant alimenté par Astro, vous pouvez ajouter la prise en charge des composants construits avec n'importe quel [cadre d'interface utilisateur pris en charge (React, Preact, Svelte, Vue, Solid, Lit et Alpine)](https://docs.astro.build/fr/core-concepts/framework-components/) dans vos fichiers MDX. -Pour en savoir plus sur [l'utilisation de composants dans MDX](https://docs.astro.build/fr/guides/markdown-content/#using-components-in-mdx), consultez la documentation Astro. - -### Compatibilité avec les styles de Starlight - -Starlight applique des styles par défaut à votre contenu Markdown, par exemple en ajoutant une marge entre les éléments. -Si ces styles entrent en conflit avec l'apparence de votre composant, définissez la classe `not-content` sur votre composant pour les désactiver. - -```astro 'class="not-content"' ---- -// src/components/Exemple.astro ---- - -<div class="not-content"> - <p>Contenu non affecté par les styles par défaut de Starlight.</p> -</div> -``` - -## Composants intégrés - -Starlight fournit quelques composants intégrés pour les cas d'utilisation courants de la documentation. -Ces composants sont disponibles dans le paquet `@astrojs/starlight/components`. - -### Onglets - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -Vous pouvez afficher une interface à onglets en utilisant les composants `<Tabs>` et `<TabItem>`. -Chaque `<TabItem>` doit avoir un `label` à afficher aux utilisateurs. -Utilisez l'attribut facultatif `icon` pour inclure l'une des [icônes intégrées de Starlight](#toutes-les-icônes) à côté de l'étiquette. - -```mdx -# src/content/docs/exemple.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="Étoiles" icon="star"> - Sirius, Véga, Bételgeuse - </TabItem> - <TabItem label="Lunes" icon="moon"> - Io, Europa, Ganymède - </TabItem> -</Tabs> -``` - -Le code ci-dessus génère les onglets suivants sur la page : - -<Tabs> - <TabItem label="Étoiles" icon="star"> - Sirius, Véga, Bételgeuse - </TabItem> - <TabItem label="Lunes" icon="moon"> - Io, Europa, Ganymède - </TabItem> -</Tabs> - -#### Onglets synchronisés - -Conservez plusieurs groupes d'onglets synchronisés en ajoutant l'attribut `syncKey`. - -Tous les composants `<Tabs>` avec la même valeur `syncKey` afficheront le même label actif. Cela permet à votre lecteur de choisir une fois (par exemple, leur système d'exploitation ou leur gestionnaire de paquets) et de voir leur choix persisté au travers de navigations entre différentes pages. - -Pour synchroniser des onglets liés, ajoutez une propriété `syncKey` identique à chaque composant `<Tabs>` et assurez-vous qu'ils utilisent tous les mêmes libellés de `<TabItem>` : - -```mdx 'syncKey="constellations"' -# src/content/docs/exemple.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -_Quelques étoiles :_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">Bellatrix, Rigel, Bételgeuse</TabItem> - <TabItem label="Gémeaux">Pollux, Castor A, Castor B</TabItem> -</Tabs> - -_Quelques exoplanètes :_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Gémeaux">Pollux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> -``` - -Le code ci-dessus génère les onglets suivants sur la page : - -_Quelques étoiles :_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">Bellatrix, Rigel, Bételgeuse</TabItem> - <TabItem label="Gémeaux">Pollux, Castor A, Castor B</TabItem> -</Tabs> - -_Quelques exoplanètes :_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Gémeaux">Pollux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> - -### Cartes - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -Vous pouvez afficher du contenu dans une boîte correspondant aux styles de Starlight en utilisant le composant `<Card>`. -Enveloppez plusieurs cartes dans le composant `<CardGrid>` pour afficher les cartes côte à côte lorsqu'il y a suffisamment d'espace. - -Une `<Card>` nécessite un `title` et peut optionnellement inclure un attribut `icon` fixé au nom de [l'une des icônes intégrées de Starlight](#toutes-les-icônes). - -```mdx -# src/content/docs/exemple.mdx - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="Regardez-ça"> - Contenu intéressant que vous souhaitez mettre en évidence. -</Card> - -<CardGrid> - <Card title="Étoiles" icon="star"> - Sirius, Véga, Bételgeuse - </Card> - <Card title="Lunes" icon="moon"> - Io, Europa, Ganymède - </Card> -</CardGrid> -``` - -Le code ci-dessus génère ce qui suit sur la page : - -<Card title="Regardez-ça"> - Contenu intéressant que vous souhaitez mettre en évidence. -</Card> - -<CardGrid> - <Card title="Étoiles" icon="star"> - Sirius, Véga, Bételgeuse - </Card> - <Card title="Lunes" icon="moon"> - Io, Europa, Ganymède - </Card> -</CardGrid> - -:::tip -Utilisez une grille de cartes sur votre page d'accueil pour afficher les principales caractéristiques de votre projet. -Ajoutez l'attribut `stagger` pour décaler verticalement la deuxième colonne de cartes et ajouter un intérêt visuel : - -```astro -<CardGrid stagger> - <!-- cards --> -</CardGrid> -``` - -::: - -### Cartes de liaison - -Utilisez le composant `<LinkCard>` pour créer un lien bien visible vers différentes pages. - -Une `<LinkCard>` nécessite les attributs `title` et [`href`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/a#href). Vous pouvez optionellement inclure une courte `description` ou d'autres attributs de lien tels que `target`. - -Regroupez plusieurs composants `<LinkCard>` dans `<CardGrid>` pour afficher les cartes côte à côte lorsqu'il y a suffisamment d'espace. - -```mdx -# src/content/docs/exemple.mdx - -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -<LinkCard - title="Personnalisation de Starlight" - description="Apprenez à personnaliser votre site Starlight avec vos propres styles, vos polices et bien plus encore." - href="/fr/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Création de contenu en Markdown" - href="/fr/guides/authoring-content/" - /> - <LinkCard title="Composants" href="/fr/guides/components/" /> -</CardGrid> -``` - -Le code ci-dessus génère ce qui suit sur la page : - -import { LinkCard } from '@astrojs/starlight/components'; - -<LinkCard - title="Personnaliser Starlight" - description="Apprenez à personnaliser votre site Starlight avec vos propres styles, vos polices et bien plus encore." - href="/fr/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Création de contenu en Markdown" - href="/fr/guides/authoring-content/" - /> - <LinkCard title="Composants" href="/fr/guides/components/" /> -</CardGrid> - -### Boutons de liaison - -Utilisez le composant `<LinkButton>` pour créer des liens visuellement distincts qui appellent à l'action (également connus sous le nom de « call-to-action » ou « CTA » en anglais). -Un bouton de liaison est utile pour diriger les utilisateurs vers le contenu le plus pertinent ou actionnable et est souvent utilisé sur les pages d'accueil. - -Un `<LinkButton>` nécessite un attribut [`href`](https://developer.mozilla.org/fr/docs/Web/HTML/Element/a#href) et accepte en option d'autres attributs de lien tels que `target`. - -L'attribut `icon` peut être défini avec le nom de [l'une des icônes intégrées à Starlight](#toutes-les-icônes) pour inclure une icône à côté du texte. -L'attribut `iconPlacement` peut être utilisé pour placer l'icône avant le texte en le définissant à `start` (par défaut à `end`). - -Personnalisez l'apparence du bouton de liaison en utilisant l'attribut `variant`, qui peut être défini à `primary` (par défaut), `secondary` ou `minimal`. - -```mdx -# src/content/docs/exemple.mdx - -import { LinkButton } from '@astrojs/starlight/components'; - -<LinkButton href="/fr/getting-started/">Mise en route</LinkButton> -<LinkButton href="https://docs.astro.build" variant="secondary" icon="external"> - Référence: Astro -</LinkButton> -``` - -Le code ci-dessus génère ce qui suit sur la page : - -import { LinkButton } from '@astrojs/starlight/components'; - -<LinkButton href="/fr/getting-started/">Mise en route</LinkButton> -<LinkButton href="https://docs.astro.build" variant="secondary" icon="external"> - Référence: Astro -</LinkButton> - -### Encarts - -Les encarts (également connus sous le nom de « admonitions » ou « asides » en anglais) sont utiles pour afficher des informations secondaires à côté du contenu principal d'une page. - -Le composant `<Aside>` peut avoir un `type` optionnel de `note` (par défaut), `tip`, `caution` ou `danger`. La définition d'un attribut `title` remplace le titre par défaut de l'encart. - -````mdx -# src/content/docs/exemple.mdx - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>Un encart par défaut sans titre personnalisé.</Aside> - -<Aside type="caution" title="Prenez garde !"> - Un encart d'avertissement *avec* un titre personnalisé. -</Aside> - -<Aside type="tip"> - -D'autres contenus sont également pris en charge dans les encarts. - -```js -// Un extrait de code, par exemple. -``` - -</Aside> - -<Aside type="danger">Ne donnez votre mot de passe à personne.</Aside> -```` - -Le code ci-dessus génère ce qui suit sur la page : - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>Un encart par défaut sans titre personnalisé.</Aside> - -<Aside type="caution" title="Prenez garde !"> - Un encart d'avertissement *avec* un titre personnalisé. -</Aside> - -<Aside type="tip"> - -D'autres contenus sont également pris en charge dans les encarts. - -```js -// Un extrait de code, par exemple. -``` - -</Aside> - -<Aside type="danger">Ne donnez votre mot de passe à personne.</Aside> - -Starlight fournit également une syntaxe personnalisée pour afficher des encarts dans du contenu Markdown et MDX comme alternative au composant `<Aside>`. -Voir le guide de [« Création de contenu en Markdown »](/fr/guides/authoring-content/#encarts) pour plus de détails sur la syntaxe personnalisée. - -### Code - -Utilisez le composant `<Code>` pour afficher du code avec coloration syntaxique lorsque l'utilisation d'un [bloc de code Markdown](/fr/guides/authoring-content/#blocs-de-code) n'est pas possible, par exemple, pour afficher des données provenant de sources externes comme des fichiers, des bases de données ou des API. - -Consultez la documentation [du « composant Code » d'Expressive Code](https://expressive-code.com/key-features/code-component/) pour plus de détails sur les props que `<Code>` supporte. - -```mdx -# src/content/docs/exemple.mdx - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log("Cela peut provenir d'un fichier ou d'un CMS !");`; -export const fileName = 'exemple.js'; -export const highlights = ['fichier', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> -``` - -Le code ci-dessus génère ce qui suit sur la page : - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log("Cela peut provenir d'un fichier ou d'un CMS !");`; -export const fileName = 'exemple.js'; -export const highlights = ['fichier', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> - -#### Code importé - -Utilisez [le suffixe d'import `?raw` de Vite](https://vitejs.dev/guide/assets#importing-asset-as-string) pour importer n'importe quel fichier de code sous forme de chaîne de caractères. -Vous pouvez ensuite passer cette chaîne importée au composant `<Code>` pour l'inclure dans votre page. - -```mdx title="src/content/docs/exemple.mdx" "?raw" -import { Code } from '@astrojs/starlight/components'; -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> -``` - -Le code ci-dessus génère ce qui suit sur la page : - -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> - -### Arborescence de fichiers - -Utilisez le composant `<FileTree>` pour afficher la structure d'un répertoire avec des icônes de fichiers et des sous-répertoires repliables. - -Spécifiez la structure de vos fichiers et répertoires avec une [liste Markdown non ordonnée](https://www.markdownguide.org/basic-syntax/#unordered-lists) dans `<FileTree>`. -Créez un sous-répertoire en utilisant une liste imbriquée ou ajoutez un `/` à la fin d'un élément de liste pour l'afficher comme un répertoire sans contenu spécifique. - -La syntaxe suivante peut être utilisée pour personnaliser l'apparence de l'arborescence des fichiers : - -- Mettez en évidence un fichier ou un répertoire en mettant son nom en gras, par exemple `**README.md**`. -- Ajoutez un commentaire à un fichier ou à un répertoire en ajoutant du texte après le nom. -- Ajoutez des fichiers et des répertoires fictifs en utilisant soit `...` soit `…` comme nom. - -```mdx -# src/content/docs/exemple.mdx - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs un fichier **important** -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> -``` - -Le code ci-dessus génère ce qui suit sur la page : - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs un fichier **important** -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> - -### Étapes - -Utilisez le composant `<Steps>` pour créer des listes de tâches numérotées. -Cela est utile pour des guides étape par étape plus complexes où chaque étape doit être clairement mise en évidence. - -Entourez une liste ordonnée standard Markdown avec le composant `<Steps>`. -Toute la syntaxe habituelle de Markdown est applicable à l'intérieur de `<Steps>`. - -````mdx title="src/content/docs/exemple.mdx" -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Importez le composant dans votre fichier MDX : - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Entourez les éléments de votre liste ordonnée de `<Steps>`. - -</Steps> -```` - -Le code ci-dessus génère ce qui suit sur la page : - -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Importez le composant dans votre fichier MDX : - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Entourez les éléments de votre liste ordonnée de `<Steps>`. - -</Steps> - -### Badges - -import { Badge } from '@astrojs/starlight/components'; - -Utilisez le composant `<Badge>` pour afficher de petits éléments d'information, tels que des statuts ou des étiquettes. - -Passez le contenu que vous souhaitez afficher à l'attribut `text` du composant `<Badge>`. - -Par défaut, le badge utilisera la couleur d'accentuation du thème de votre site. Pour utiliser une couleur de badge intégrée, définissez l'attribut `variant` à l'une des valeurs suivantes : `note` (bleu), `tip` (violet), `danger` (rouge), `caution` (orange), ou `success` (vert). - -L'attribut `size` (par défaut : `small`) contrôle la taille du texte du badge. Les valeurs `medium` et `large` sont également disponibles pour afficher un badge plus grand. - -Pour une personnalisation plus poussée, utilisez d'autres attributs de l'élément `<span>` tels que `class` ou `style` avec du CSS personnalisé. - -```mdx title="src/content/docs/example.mdx" -import { Badge } from '@astrojs/starlight/components'; - -<Badge text="Nouveau" variant="tip" size="small" /> -<Badge text="Obsolète" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Personnalisé" variant="success" style={{ fontStyle: 'italic' }} /> -``` - -Le code ci-dessus génère ce qui suit sur la page : - -<Badge text="Nouveau" variant="tip" size="small" /> -<Badge text="Déclassé" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Personnalisé" variant="success" style={{ fontStyle: 'italic' }} /> - -### Icônes - -import { Icon } from '@astrojs/starlight/components'; -import IconsList from '~/components/icons-list.astro'; - -Starlight fournit un ensemble d'icônes courantes que vous pouvez afficher dans votre contenu à l'aide du composant `<Icon>`. - -Chaque `<Icon>` nécessite un attribut [`name`](#toutes-les-icônes) et peut optionnellement inclure un `label` pour fournir un contexte aux lecteurs d'écran. -Les attributs `size` et `color` peuvent être utilisés pour ajuster l'apparence de l'icône en utilisant des unités et valeurs de couleur CSS. - -```mdx -# src/content/docs/exemple.mdx - -import { Icon } from '@astrojs/starlight/components'; - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> -``` - -Le code ci-dessus génère ce qui suit sur la page : - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> - -#### Toutes les icônes - -Une liste de toutes les icônes disponibles est affichée ci-dessous avec leurs noms associés. Cliquez sur une icône pour copier le code du composant. - -<IconsList /> diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx index 810b17f8..7045ba5f 100644 --- a/docs/src/content/docs/getting-started.mdx +++ b/docs/src/content/docs/getting-started.mdx @@ -91,7 +91,7 @@ Read more about file-based routing and support for MDX and Markdoc files in the - **Configure:** Learn about common options in [“Customizing Starlight”](/guides/customization/). - **Navigate:** Set up your sidebar with the [“Sidebar Navigation”](/guides/sidebar/) guide. -- **Components:** Discover built-in cards, tabs, and more in the [“Components”](/guides/components/) guide. +- **Components:** Discover built-in cards, tabs, and more in the [“Components”](/components/using-components/) guide. - **Deploy:** Publish your work with the [“Deploy your site”](https://docs.astro.build/en/guides/deploy/) guide in the Astro docs. ## Updating Starlight diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx deleted file mode 100644 index 4776ae77..00000000 --- a/docs/src/content/docs/guides/components.mdx +++ /dev/null @@ -1,505 +0,0 @@ ---- -title: Components -description: Using components in MDX with Starlight. ---- - -Components let you easily reuse a piece of UI or styling consistently. -Examples might include a link card or a YouTube embed. -Starlight supports the use of components in [MDX](https://mdxjs.com/) files and provides some common components for you to use. - -[Learn more about building components in the Astro Docs](https://docs.astro.build/en/core-concepts/astro-components/). - -## Using a component - -You can use a component by importing it into your MDX file and then rendering it as a JSX tag. -These look like HTML tags but start with an uppercase letter matching the name in your `import` statement: - -```mdx ---- -# src/content/docs/example.mdx -title: Welcome to my docs ---- - -import SomeComponent from '../../components/SomeComponent.astro'; -import AnotherComponent from '../../components/AnotherComponent.astro'; - -<SomeComponent prop="something" /> - -<AnotherComponent> - Components can also contain **nested content**. -</AnotherComponent> -``` - -Because Starlight is powered by Astro, you can add support for components built with any [supported UI framework (React, Preact, Svelte, Vue, Solid, Lit, and Alpine)](https://docs.astro.build/en/core-concepts/framework-components/) in your MDX files. -Learn more about [using components in MDX](https://docs.astro.build/en/guides/markdown-content/#using-components-in-mdx) in the Astro docs. - -### Compatibility with Starlight’s styles - -Starlight applies default styling to your Markdown content, for example adding margin between elements. -If these styles conflict with your component’s appearance, set the `not-content` class on your component to disable them. - -```astro 'class="not-content"' ---- -// src/components/Example.astro ---- - -<div class="not-content"> - <p>Not impacted by Starlight’s default content styling.</p> -</div> -``` - -## Built-in components - -Starlight provides some built-in components for common documentation use cases. -These components are available from the `@astrojs/starlight/components` package. - -### Tabs - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -You can display a tabbed interface using the `<Tabs>` and `<TabItem>` components. -Each `<TabItem>` must have a `label` to display to users. -Use the optional `icon` attribute to include one of [Starlight’s built-in icons](#all-icons) next to the label. - -```mdx -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="Stars" icon="star"> - Sirius, Vega, Betelgeuse - </TabItem> - <TabItem label="Moons" icon="moon"> - Io, Europa, Ganymede - </TabItem> -</Tabs> -``` - -The code above generates the following tabs on the page: - -<Tabs> - <TabItem label="Stars" icon="star"> - Sirius, Vega, Betelgeuse - </TabItem> - <TabItem label="Moons" icon="moon"> - Io, Europa, Ganymede - </TabItem> -</Tabs> - -#### Synced tabs - -Keep multiple tab groups synchronized by adding the `syncKey` attribute. - -All `<Tabs>` with the same `syncKey` value will display the same active label. This allows your reader to choose once (e.g. their operating system or package manager), and see their choice persisted across page navigations. - -To synchronize related tabs, add an identical `syncKey` property to each `<Tabs>` component and ensure that they all use the same `<TabItem>` labels: - -```mdx 'syncKey="constellations"' -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -_Some stars:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem> - <TabItem label="Gemini">Pollux, Castor A, Castor B</TabItem> -</Tabs> - -_Some exoplanets:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> -``` - -The code above generates the following on the page: - -_Some stars:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem> - <TabItem label="Gemini">Pollux, Castor A, Castor B</TabItem> -</Tabs> - -_Some exoplanets:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> - -### Cards - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -You can display content in a box matching Starlight’s styles using the `<Card>` component. -Wrap multiple cards in the `<CardGrid>` component to display cards side-by-side when there’s enough space. - -A `<Card>` requires a `title` and can optionally include an `icon` attribute set to the name of [one of Starlight’s built-in icons](#all-icons). - -```mdx -# src/content/docs/example.mdx - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="Check this out">Interesting content you want to highlight.</Card> - -<CardGrid> - <Card title="Stars" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Moons" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> -``` - -The code above generates the following on the page: - -<Card title="Check this out">Interesting content you want to highlight.</Card> - -<CardGrid> - <Card title="Stars" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Moons" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> - -:::tip -Use a card grid on your home page to display your project’s key features. -Add the `stagger` attribute to shift the second column of cards vertically and add visual interest: - -```astro -<CardGrid stagger> - <!-- cards --> -</CardGrid> -``` - -::: - -### Link Cards - -Use the `<LinkCard>` component to link prominently to different pages. - -A `<LinkCard>` requires a `title` and an [`href`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href) attribute. You can optionally include a short `description` or other link attributes such as `target`. - -Group multiple `<LinkCard>` components in `<CardGrid>` to display cards side-by-side when there’s enough space. - -```mdx -# src/content/docs/example.mdx - -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -<LinkCard - title="Customizing Starlight" - description="Learn how to make your Starlight site your own with custom styles, fonts, and more." - href="/guides/customization/" -/> - -<CardGrid> - <LinkCard title="Authoring Markdown" href="/guides/authoring-content/" /> - <LinkCard title="Components" href="/guides/components/" /> -</CardGrid> -``` - -The above code generates the following on the page: - -import { LinkCard } from '@astrojs/starlight/components'; - -<LinkCard - title="Customizing Starlight" - description="Learn how to make your Starlight site your own with custom styles, fonts, and more." - href="/guides/customization/" -/> - -<CardGrid> - <LinkCard title="Authoring Markdown" href="/guides/authoring-content/" /> - <LinkCard title="Components" href="/guides/components/" /> -</CardGrid> - -### Link Buttons - -Use the `<LinkButton>` component for visually distinct call-to-action links. -A link button is useful for directing users to the most relevant or actionable content and often used on landing pages - -A `<LinkButton>` requires an [`href`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href) attribute and optionally accepts other link attributes such as `target`. - -The `icon` attribute can optionally be set to the name of [one of Starlight's built-in icons](#all-icons) to include an icon next to the text. -The `iconPlacement` attribute can be used to place the icon before the text by setting it to `start` (defaults to `end`). - -Customize the appearance of the link button using the `variant` attribute, which can be set to `primary` (the default), `secondary`, or `minimal`. - -```mdx -# src/content/docs/example.mdx - -import { LinkButton } from '@astrojs/starlight/components'; - -<LinkButton href="/getting-started/">Get started</LinkButton> -<LinkButton href="https://docs.astro.build" variant="secondary" icon="external"> - Related: Astro -</LinkButton> -``` - -The above code generates the following on the page: - -import { LinkButton } from '@astrojs/starlight/components'; - -<LinkButton href="/getting-started/">Get started</LinkButton> -<LinkButton href="https://docs.astro.build" variant="secondary" icon="external"> - Related: Astro -</LinkButton> - -### Asides - -Asides (also known as “admonitions” or “callouts”) are useful for displaying secondary information alongside a page’s main content. - -An `<Aside>` can have an optional `type` of `note` (the default), `tip`, `caution` or `danger`. Setting a `title` attribute overrides the default aside title. - -````mdx -# src/content/docs/example.mdx - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>A default aside without a custom title.</Aside> - -<Aside type="caution" title="Watch out!"> - A warning aside *with* a custom title. -</Aside> - -<Aside type="tip"> - -Other content is also supported in asides. - -```js -// A code snippet, for example. -``` - -</Aside> - -<Aside type="danger">Do not give your password to anyone.</Aside> -```` - -The above code generates the following on the page: - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>A default aside without a custom title.</Aside> - -<Aside type="caution" title="Watch out!"> - A warning aside *with* a custom title. -</Aside> - -<Aside type="tip"> - -Other content is also supported in asides. - -```js -// A code snippet, for example. -``` - -</Aside> - -<Aside type="danger">Do not give your password to anyone.</Aside> - -Starlight also provides a custom syntax for rendering asides in Markdown and MDX as an alternative to the `<Aside>` component. -See the [“Authoring Content in Markdown”](/guides/authoring-content/#asides) guide for details of the custom syntax. - -### Code - -Use the `<Code>` component to render syntax highlighted code when using a [Markdown code block](/guides/authoring-content/#code-blocks) is not possible, for example, to render data coming from external sources like files, databases, or APIs. - -See the [Expressive Code “Code Component” docs](https://expressive-code.com/key-features/code-component/) for full details of the props `<Code>` supports. - -```mdx -# src/content/docs/example.mdx - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('This could come from a file or CMS!');`; -export const fileName = 'example.js'; -export const highlights = ['file', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> -``` - -The code above generates the following on the page: - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('This could come from a file or CMS!');`; -export const fileName = 'example.js'; -export const highlights = ['file', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> - -#### Imported Code - -Use [Vite’s `?raw` import suffix](https://vitejs.dev/guide/assets#importing-asset-as-string) to import any code file as a string. -You can then pass this imported string to the `<Code>` component to include it on your page. - -```mdx title="src/content/docs/example.mdx" "?raw" -import { Code } from '@astrojs/starlight/components'; -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> -``` - -The code above generates the following on the page: - -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> - -### File Tree - -Use the `<FileTree>` component to display the structure of a directory with file icons and collapsible sub-directories. - -Specify the structure of your files and directories with an [unordered Markdown list](https://www.markdownguide.org/basic-syntax/#unordered-lists) inside `<FileTree>`. -Create a sub-directory using a nested list or add a `/` to the end of a list item to render it as a directory without specific content. - -The following syntax can be used to customize the appearance of the file tree: - -- Highlight a file or directory by making its name bold, e.g. `**README.md**`. -- Add a comment to a file or directory by adding more text after the name. -- Add placeholder files and directories by using either `...` or `…` as the name. - -```mdx -# src/content/docs/example.mdx - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs an **important** file -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> -``` - -The above code generates the following on the page: - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs an **important** file -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> - -### Steps - -Use the `<Steps>` component to style numbered lists of tasks. -This is useful for more complex step-by-step guides where each step needs to be clearly highlighted. - -Wrap `<Steps>` around a standard Markdown ordered list. -All the usual Markdown syntax is applicable inside `<Steps>`. - -````mdx title="src/content/docs/example.mdx" -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Import the component into your MDX file: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Wrap `<Steps>` around your ordered list items. - -</Steps> -```` - -The code above generates the following on the page: - -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Import the component into your MDX file: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Wrap `<Steps>` around your ordered list items. - -</Steps> - -### Badges - -import { Badge } from '@astrojs/starlight/components'; - -Use the `<Badge>` component to display small pieces of information, such as status or labels. - -Pass the content you want to display to the `text` attribute of the `<Badge>` component. - -By default, the badge will use the theme accent color of your site. To use a built-in badge color, set the `variant` attribute to one of the following values: `note` (blue), `tip` (purple), `danger` (red), `caution` (orange), or `success` (green). - -The `size` attribute (default: `small`) controls the size of the badge text. `medium` and `large` are also available options for displaying a larger badge. - -For further customization, use other `<span>` attributes such as `class` or `style` with custom CSS. - -```mdx title="src/content/docs/example.mdx" -import { Badge } from '@astrojs/starlight/components'; - -<Badge text="New" variant="tip" size="small" /> -<Badge text="Deprecated" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Custom" variant="success" style={{ fontStyle: 'italic' }} /> -``` - -The code above generates the following on the page: - -<Badge text="New" variant="tip" size="small" /> -<Badge text="Deprecated" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Custom" variant="success" style={{ fontStyle: 'italic' }} /> - -### Icon - -import { Icon } from '@astrojs/starlight/components'; -import IconsList from '~/components/icons-list.astro'; - -Starlight provides a set of common icons that you can display in your content using the `<Icon>` component. - -Each `<Icon>` requires a [`name`](#all-icons) and can optionally include a `label` to provide context for screen readers. -The `size` and `color` attributes can be used to adjust the icon’s appearance using CSS units and color values. - -```mdx -# src/content/docs/example.mdx - -import { Icon } from '@astrojs/starlight/components'; - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> -``` - -The code above generates the following on the page: - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> - -#### All icons - -A list of all available icons is shown below with their associated names. Click an icon to copy the component code for it. - -<IconsList /> diff --git a/docs/src/content/docs/hi/getting-started.mdx b/docs/src/content/docs/hi/getting-started.mdx index e0efd07d..f770982e 100644 --- a/docs/src/content/docs/hi/getting-started.mdx +++ b/docs/src/content/docs/hi/getting-started.mdx @@ -91,7 +91,7 @@ Starlight आपके लिए नई सामग्री जोड़ने - **कॉन्फ़िगर:** ["कस्टमाइज़िंग स्टारलाइट"](/hi/guides/customization/) में सामान्य विकल्पों के बारे में जानें। - **नेविगेट:** ["साइडबार नेविगेशन"](/hi/guides/sidebar/) गाइड के साथ अपना साइडबार सेट करें। -- **अवयवों:** ["अवयवों"](/hi/guides/components/) मार्गदर्शिका में अंतर्निहित कार्ड, टैब और बहुत कुछ खोजें। +- **अवयवों:** ["अवयवों"](/hi/components/using-components/) मार्गदर्शिका में अंतर्निहित कार्ड, टैब और बहुत कुछ खोजें। - **डिप्लॉय:** Astro Docs में ["अपनी साइट परिनियोजित करें"](https://docs.astro.build/hi/guides/deploy/) मार्गदर्शिका के साथ अपना कार्य प्रकाशित करें। ## Starlight को अद्यतन करें diff --git a/docs/src/content/docs/hi/guides/components.mdx b/docs/src/content/docs/hi/guides/components.mdx deleted file mode 100644 index c4f43936..00000000 --- a/docs/src/content/docs/hi/guides/components.mdx +++ /dev/null @@ -1,427 +0,0 @@ ---- -title: अवयवों -description: Starlight के साथ MDX में अवयवों का उपयोग करना जाने। ---- - -अवयव आपको आसानी से UI के एक टुकड़े या शैलियों का लगातार पुन: उपयोग करने देते हैं। -उदाहरणों में एक लिंक कार्ड या YouTube embed शामिल हो सकता है। -Starlight [MDX](https://mdxjs.com/) फ़ाइलों में अवयवों के उपयोग का समर्थन करता है और आपके उपयोग के लिए कुछ सामान्य अवयव प्रदान करता है। - -[Astro दस्तावेज़ीकरण के माध्यम से अवयवों के निर्माण के बारे में और जानें](https://docs.astro.build/hi/core-concepts/astro-components/)। - -## जाने कैसे एक अवयव का उपयोग करें - -आप किसी अवयव को अपने MDX फ़ाइल में आयात करके और फिर उसे JSX टैग के रूप में प्रस्तुत करके उपयोग कर सकते हैं। -ये HTML टैग्स की तरह दिखते हैं लेकिन आपके `import` कथन में नाम से मेल खाने वाले बड़े अक्षर से शुरू होते हैं: - -```mdx ---- -# src/content/docs/example.mdx -title: मेरे दस्तावेज़ में आपका स्वागत है ---- - -import SomeComponent from '../../components/SomeComponent.astro'; -import AnotherComponent from '../../components/AnotherComponent.astro'; - -<SomeComponent prop="something" /> - -<AnotherComponent> - अवयवों में **नेस्टेड कंटेंट** भी हो सकती है। -</AnotherComponent> -``` - -क्योंकि Starlight Astro द्वारा संचालित है, आप अपने MDX फ़ाइलों में किसी भी [समर्थित UI फ्रेमवर्क (React, Preact, Svelte, Vue, Solid, Lit और Alpine)](https://docs.astro.build/hi/core-concepts/framework-components/) के साथ निर्मित अवयवों के लिए समर्थन जोड़ सकते हैं। -Astro दस्तावेज़ीकरण में [MDX में अवयवों का उपयोग करने](https://docs.astro.build/hi/guides/markdown-content/#using-components-in-mdx) के बारे में और जानें। - -### Starlight की शैलियों के साथ संगतता - -Starlight आपके Markdown कंटेंट पर डिफ़ॉल्ट शैलि लागू करता है, उदाहरण के लिए तत्वों के बीच margin जोड़ना। -यदि ये शैलियाँ आपके अवयव की उपस्थिति के साथ संघर्ष करती हैं, तो उन्हें अक्षम करने के लिए अपने अवयव पर `not-content` वर्ग सेट करें। - -```astro 'class="not-content"' ---- -// src/components/Example.astro ---- - -<div class="not-content"> - <p>Starlight की डिफ़ॉल्ट कंटेंट शैली से प्रभावित नहीं।</p> -</div> -``` - -## अंतर्निर्मित अवयव - -Starlight सामान्य दस्तावेज़ीकरण उपयोग मामलों के लिए कुछ अंतर्निहित अवयव प्रदान करता है। -ये अवयव `@astrojs/starlight/components` पैकेज से उपलब्ध हैं। - -### टैब - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -आप `<Tabs>` और `<TabItem>` अवयवों का उपयोग करके एक टैब्ड इंटरफ़ेस प्रदर्शित कर सकते हैं। -प्रत्येक `<TabItem>` में उपयोगकर्ताओं को प्रदर्शित करने के लिए एक `label` होना चाहिए। -लेबल के आगे [Starlight के अंतर्निर्मित आइकन](#सभी-आइकन) में से एक को शामिल करने के लिए वैकल्पिक `icon` विशेषता का उपयोग करें। - -```mdx -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="Stars" icon="star"> - Sirius, Vega, Betelgeuse - </TabItem> - <TabItem label="Moons" icon="moon"> - Io, Europa, Ganymede - </TabItem> -</Tabs> -``` - -उपरोक्त कोड पेज पर निम्नलिखित टैब उत्पन्न करता है: - -<Tabs> - <TabItem label="Stars" icon="star"> - Sirius, Vega, Betelgeuse - </TabItem> - <TabItem label="Moons" icon="moon"> - Io, Europa, Ganymede - </TabItem> -</Tabs> - -### कार्ड - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -आप `<Card>` अवयव का उपयोग करके Starlight की शैलियों से मेल खाने वाले बक्से में कंटेंट प्रदर्शित कर सकते हैं। -पर्याप्त जगह होने पर कार्डों को एक साथ प्रदर्शित करने के लिए `<CardGrid>` अवयव में एकाधिक कार्ड लपेटें। - -एक `<Card>` के लिए एक `title` की आवश्यकता होती है और इसमें वैकल्पिक रूप से [Starlight के अंतर्निहित आइकनों में से एक](#सभी-आइकन) के नाम पर सेट एक `icon` विशेषता शामिल हो सकती है। - -```mdx -# src/content/docs/example.mdx - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="इसको देखे">दिलचस्प कंटेंट जिसे आप हाइलाइट करना चाहते हैं।</Card> - -<CardGrid> - <Card title="सितारे" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="चन्द्रमा" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> -``` - -उपरोक्त कोड पेज पर निम्नलिखित उत्पन्न करता है: - -<Card title="इसको देखे">दिलचस्प कंटेंट जिसे आप हाइलाइट करना चाहते हैं।</Card> - -<CardGrid> - <Card title="सितारे" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="चन्द्रमा" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> - -:::tip -अपने परियोजना की मुख्य विशेषताओं को प्रदर्शित करने के लिए अपने होम पेज पर एक कार्ड ग्रिड का उपयोग करें। -कार्ड के दूसरे कॉलम को लंबवत रूप से स्थानांतरित करने और दृश्य रुचि जोड़ने के लिए `stagger` विशेषता जोड़ें: - -```astro -<CardGrid stagger> - <!-- cards --> -</CardGrid> -``` - -::: - -### लिंक कार्ड - -विभिन्न पेजों को प्रमुखता से लिंक करने के लिए `<LinkCard>` अवयव का उपयोग करें। - -`<LinkCard>` के लिए एक `title` और एक [`href`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href) विशेषता की आवश्यकता होती है। आप वैकल्पिक रूप से एक संक्षिप्त `description` या `target` जैसी अन्य लिंक विशेषताएँ शामिल कर सकते हैं। - -पर्याप्त जगह होने पर कार्डों को एक साथ प्रदर्शित करने के लिए `<CardGrid>` में कई `<LinkCard>` अवयवों को समूहित करें। - -```mdx -# src/content/docs/example.mdx - -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -<LinkCard - title="स्टारलाईट को अनुकूलित करना" - description="जानें कि कस्टम शैलियों, फ़ॉन्ट और बहुत कुछ के साथ अपनी Starlight साइट को कैसे अपना बनाएं।" - href="/hi/guides/customization/" -/> - -<CardGrid> - <LinkCard title="Markdown का संलेखन" href="/hi/guides/authoring-content/" /> - <LinkCard title="अवयवों" href="/hi/guides/components/" /> -</CardGrid> -``` - -उपरोक्त कोड पेज पर निम्नलिखित उत्पन्न करता है: - -import { LinkCard } from '@astrojs/starlight/components'; - -<LinkCard - title="स्टारलाईट को अनुकूलित करना" - description="जानें कि कस्टम शैलियों, फ़ॉन्ट और बहुत कुछ के साथ अपनी Starlight साइट को कैसे अपना बनाएं।" - href="/hi/guides/customization/" -/> - -<CardGrid> - <LinkCard title="Markdown का संलेखन" href="/hi/guides/authoring-content/" /> - <LinkCard title="अवयवों" href="/hi/guides/components/" /> -</CardGrid> - -### असाइड्स - -असाइड्स (जिन्हें "चेतावनी" या "कॉलआउट" के रूप में भी जाना जाता है) किसी पेज की मुख्य सामग्री के साथ-साथ द्वितीयक जानकारी प्रदर्शित करने के लिए उपयोगी होते हैं। - -एक `<Aside>` में `note` (डिफ़ॉल्ट), `tip`, `caution` या `danger` का वैकल्पिक `type` हो सकता है। `title` विशेषता सेट करना डिफ़ॉल्ट असाइड् शीर्षक को ओवरराइड करता है। - -````mdx -# src/content/docs/example.mdx - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>कस्टम शीर्षक के बिना एक डिफ़ॉल्ट असाइड्।</Aside> - -<Aside type="caution" title="ध्यान रहें!"> - एक कस्टम शीर्षक के *साथ* एक चेतावनी वाला असाइड्। -</Aside> - -<Aside type="tip"> - -असाइड्स में अन्य कंटेंट भी अलग से समर्थित है। - -```js -// उदाहरण के लिए, एक कोड स्निपेट। -``` - -</Aside> - -<Aside type="danger">आप अपना पासवर्ड किसी को न दें।</Aside> -```` - -उपरोक्त कोड पेज पर निम्नलिखित उत्पन्न करता है: - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>कस्टम शीर्षक के बिना एक डिफ़ॉल्ट असाइड्।</Aside> - -<Aside type="caution" title="ध्यान रहें!"> - एक कस्टम शीर्षक के *साथ* एक चेतावनी वाला असाइड्। -</Aside> - -<Aside type="tip"> - -असाइड्स में अन्य कंटेंट भी अलग से समर्थित है। - -```js -// उदाहरण के लिए, एक कोड स्निपेट। -``` - -</Aside> - -<Aside type="danger">आप अपना पासवर्ड किसी को न दें।</Aside> - -Starlight `<Aside>` अवयव के विकल्प के रूप में Markdown” और MDX में असाइड् प्रस्तुत करने के लिए एक कस्टम सिंटैक्स भी प्रदान करता है। -कस्टम सिंटैक्स के विवरण के लिए ["Markdown में कंटेंट संलेखन"](/hi/guides/authoring-content/#asides) मार्गदर्शिका देखें। - -### कोड - -जब [Markdown कोड ब्लॉक](/hi/guides/authoring-content/#code-blocks) का उपयोग करना संभव नहीं हो, तब सिंटैक्स हाइलाइट किए गए कोड को रेंडर करने के लिए `<Code>` अवयव का उपयोग करें, उदाहरण के लिए, फ़ाइलों, डेटाबेस, या APIs जैसे बाहरी स्रोतों से आने वाले डेटा को रेंडर करना। - -`<Code>` द्वारा समर्थित प्रॉप्स की पूरी जानकारी के लिए [Expressive Code "Code अवयव" दस्तावेज़](https://expressive-code.com/key-features/code-component/) देखें। - -```mdx -# src/content/docs/example.mdx - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('यह किसी फ़ाइल या CMS से आ सकता है!');`; -export const fileName = 'example.js'; -export const highlights = ['फ़ाइल', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> -``` - -उपरोक्त कोड पेज पर निम्नलिखित उत्पन्न करता है: - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('यह किसी फ़ाइल या CMS से आ सकता है!');`; -export const fileName = 'example.js'; -export const highlights = ['फ़ाइल', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> - -#### आयातित कोड - -किसी भी कोड फ़ाइल को स्ट्रिंग के रूप में आयात करने के लिए [Vite के `?raw` आयात प्रत्यय](https://vitejs.dev/guide/assets#importing-asset-as-string) का उपयोग करें। -फिर आप इस आयातित स्ट्रिंग को अपने पृष्ठ पर शामिल करने के लिए `<Code>` अवयव में पास कर सकते हैं। - -```mdx title="src/content/docs/example.mdx" "?raw" -import { Code } from '@astrojs/starlight/components'; -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> -``` - -उपरोक्त कोड पेज पर निम्नलिखित उत्पन्न करता है: - -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> - -### फ़ाइल वृक्ष - -फ़ाइल आइकन और बंधने योग्य उप-निर्देशिकाओं के साथ निर्देशिका की संरचना प्रदर्शित करने के लिए `<FileTree>` घटक का उपयोग करें। - -`<FileTree>` के अंदर एक [अव्यवस्थित Markdown सूची](https://www.markdownguide.org/basic-syntax/#unordered-lists) के साथ अपनी फ़ाइलों और निर्देशिकाओं की संरचना निर्दिष्ट करें। नेस्टेड सूची का उपयोग करके एक उप-निर्देशिका बनाएं या इसे विशिष्ट सामग्री के बिना निर्देशिका के रूप में प्रस्तुत करने के लिए सूची आइटम के अंत में `/` जोड़ें। - -फ़ाइल वृक्ष के स्वरूप को अनुकूलित करने के लिए निम्नलिखित सिंटैक्स का उपयोग किया जा सकता है: - -- किसी फ़ाइल या निर्देशिका का नाम बोल्ड करके उसे हाइलाइट करें, उदा. `**README.md**` पढ़ें. -- किसी फ़ाइल या निर्देशिका में नाम के बाद और टेक्स्ट जोड़कर एक टिप्पणी जोड़ें। -- नाम के रूप में `...`. या `…` का उपयोग करके प्लेसहोल्डर फ़ाइलें और निर्देशिकाएँ जोड़ें। - -```mdx -# src/content/docs/example.mdx - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs an **important** file -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> -``` - -उपरोक्त कोड पृष्ठ पर निम्नलिखित उत्पन्न करता है: - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs एक **महत्वपूर्ण** फ़ाइल -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> - -### चरण - -कार्यों की क्रमांकित सूचियों को स्टाइल करने के लिए `<चरण>` घटक का उपयोग करें। -यह अधिक जटिल चरण-दर-चरण मार्गदर्शिकाओं के लिए उपयोगी है जहां प्रत्येक चरण को स्पष्ट रूप से हाइलाइट करने की आवश्यकता होती है। - -`<चरण>` को मानक Markdown आदेशित सूची के चारों ओर लपेटें। -सभी सामान्य Markdown सिंटैक्स `<Steps>` के अंदर लागू होते हैं। - -````mdx title="src/content/docs/example.mdx" -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. अवयव को अपनी MDX फ़ाइल में आयात करें: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. अपने ऑर्डर किए गए सूची आइटम के चारों ओर `<Steps>` लपेटें। - -</Steps> -```` - -उपरोक्त कोड पृष्ठ पर निम्नलिखित उत्पन्न करता है: - -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. अवयव को अपनी MDX फ़ाइल में आयात करें: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. अपने ऑर्डर किए गए सूची आइटम के चारों ओर `<Steps>` लपेटें। - -</Steps> - -### बैज - -import { Badge } from '@astrojs/starlight/components'; - -स्थिति या लेबल जैसी छोटी जानकारी प्रदर्शित करने के लिए `<Badge>` अवयव का उपयोग करें। - -वह सामग्री जिसे आप प्रदर्शित करना चाहते हैं उसे `<Badge>` अवयव की `text` विशेषता में भेजे। - -डिफ़ॉल्ट रूप से, बैज आपकी साइट के थीम एक्सेंट रंग का उपयोग करेगा। बिल्ट-इन बैज रंग का उपयोग करने के लिए, `variant` विशेषता को निम्न मानों में से किसी एक पर सेट करें: `note` (नीला), `tip` (बैंगनी), `danger` (लाल), `caution` (नारंगी), या `success` (हरा)। - -`size` विशेषता (डिफ़ॉल्ट: `small`) बैज पाठ के आकार को नियंत्रित करती है। बड़ा बैज प्रदर्शित करने के लिए `medium` और `large` भी उपलब्ध विकल्प हैं। - -आगे के अनुकूलन के लिए, कस्टम CSS के साथ `<span>` विशेषताओं जैसे `class` या `style` का उपयोग करें। - -```mdx title="src/content/docs/example.mdx" -import { Badge } from '@astrojs/starlight/components'; - -<Badge text="नया" variant="tip" size="small" /> -<Badge text="पदावनत" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="कस्टम" variant="success" style={{ fontStyle: 'italic' }} /> -``` - -उपरोक्त कोड पृष्ठ पर निम्नलिखित उत्पन्न करता है: - -<Badge text="नया" variant="tip" size="small" /> -<Badge text="पदावनत" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="कस्टम" variant="success" style={{ fontStyle: 'italic' }} /> - -### आइकन - -import { Icon } from '@astrojs/starlight/components'; -import IconsList from '~/components/icons-list.astro'; - -Starlight सामान्य आइकन का एक संग्रह प्रदान करता है जिसे आप `<Icon>` अवयव का उपयोग करके अपने कंटेंट में प्रदर्शित कर सकते हैं। - -प्रत्येक `<Icon>` को एक [`name`](#सभी-आइकन) की आवश्यकता होती है और स्क्रीन रीडर के लिए संदर्भ प्रदान करने के लिए वैकल्पिक रूप से एक `label` शामिल किया जा सकता है। CSS इकाइयों और रंग मूल्यों का उपयोग करके आइकन की उपस्थिति को अनुकूलित करने के लिए `size` और `color` विशेषताओं का उपयोग किया जा सकता है। - -```mdx -# src/content/docs/example.mdx - -import { Icon } from '@astrojs/starlight/components'; - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> -``` - -उपरोक्त कोड पेज पर निम्नलिखित उत्पन्न करता है: - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> - -#### सभी आइकन - -सभी उपलब्ध आइकनों की एक सूची उनके संबंधित नामों के साथ नीचे दिखाई गई है। इसके अवयव कोड की प्रतिलिपि बनाने के लिए किसी भी आइकन पर क्लिक करें। - -<IconsList /> diff --git a/docs/src/content/docs/id/getting-started.mdx b/docs/src/content/docs/id/getting-started.mdx index 05964a63..f1a45cb6 100644 --- a/docs/src/content/docs/id/getting-started.mdx +++ b/docs/src/content/docs/id/getting-started.mdx @@ -91,7 +91,7 @@ Baca selengkapnya tentang perutean berbasis file serta dukungan untuk MDX dan Ma - **Mengkonfigurasi:** Pelajari tentang opsi umum dalam ["Menyesuaikan Starlight”](/id/guides/customization/). - **Navigasi:** Siapkan sidebar Anda dengan panduan ["Navigasi Sidebar”](/id/guides/sidebar/). -- **Komponen:** Temukan kartu, tab dan bawaan lainnya di dalam panduan ["Komponen”](/id/guides/components/). +- **Komponen:** Temukan kartu, tab dan bawaan lainnya di dalam panduan ["Komponen”](/id/components/using-components/). - **Sebarkan:** Publikasikan karya Anda dengan panduan [“_Deploy_ situs Anda”](https://docs.astro.build/en/guides/deploy/) di dokumentasi Astro. ## Memperbarui Starlight diff --git a/docs/src/content/docs/id/guides/components.mdx b/docs/src/content/docs/id/guides/components.mdx deleted file mode 100644 index 5efaa87d..00000000 --- a/docs/src/content/docs/id/guides/components.mdx +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: Komponen -description: Menggunakan komponen dalam MDX dengan Starlight. ---- - -Komponen memungkinkan Anda dengan mudah menggunakan kembali bagian UI atau _style_ secara konsisten. -Contohnya mungkin kartu tautan atau _YouTube embed_. -Starlight mendukung penggunaan komponen dalam file [MDX](https://mdxjs.com/) dan menyediakan beberapa komponen umum yang dapat Anda gunakan. - -[Pelajari lebih lanjut tentang membuat komponen di Astro Docs](https://docs.astro.build/en/core-concepts/astro-components/). - -## Menggunakan Komponen - -Anda dapat menggunakan komponen dengan mengimpornya ke dalam file MDX Anda dan kemudian merendernya sebagai tag JSX. -Tag-tag ini mirip dengan tag HTML tetapi dimulai dengan huruf kapital yang sesuai dengan nama dalam pernyataan `import` Anda: - -```mdx ---- -# src/content/docs/index.mdx -title: Selamat datang di website dokumentasi saya ---- - -import SomeComponent from '../../components/SomeComponent.astro'; -import AnotherComponent from '../../components/AnotherComponent.astro'; - -<SomeComponent prop="sesuatu" /> - -<AnotherComponent> - Komponen juga dapat berisi **konten bertingkat**. -</AnotherComponent> -``` - -Karena Starlight dibuat dengan Astro, Anda dapat menambahkan dukungan untuk komponen yang dibangun dengan berbagai [_UI framework_ yang didukung (React, Preact, Svelte, Vue, Solid, Lit, dan Alpine)](https://docs.astro.build/en/core-concepts/framework-components/) dalam file MDX Anda. -Pelajari lebih lanjut tentang menggunakan [komponen dalam MDX](https://docs.astro.build/en/guides/markdown-content/#using-components-in-mdx) di website dokumentasi Astro. - -### Kompatibilitas dengan style Starlight - -Starlight menerapkan _style_ default pada konten Markdown Anda, misalnya menambahkan margin antara elemen-elemen. -Jika _style_ ini tidak sesuai dengan tampilan komponen Anda, atur kelas `not-content` pada komponen untuk menonaktifkannya. - -```astro ---- -// src/components/Example.astro ---- - -<div class="not-content"> - <p>Tidak terpengaruh oleh style konten default Starlight.</p> -</div> -``` - -## Komponen Bawaan - -Starlight menyediakan beberapa komponen bawaan yang umum digunakan untuk keperluan dokumentasi. -Komponen ini tersedia di _package_ `@astrojs/starlight/components`. - -### Tabs - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -Anda dapat menampilkan _interface_ berbasis tab menggunakan komponen `<Tabs>` dan `<TabItem>`. -Setiap `<TabItem>` harus memiliki `label` untuk ditampilkan kepada pengguna. - -```mdx -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="Bintang">Sirius, Vega, Betelgeuse</TabItem> - <TabItem label="Bulan">Io, Europa, Ganymede</TabItem> -</Tabs> -``` - -Kode di atas akan menampilkan tab seperti berikut pada halaman: - -<Tabs> - <TabItem label="Bintang">Sirius, Vega, Betelgeuse</TabItem> - <TabItem label="Bulan">Io, Europa, Ganymede</TabItem> -</Tabs> - -### Cards - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -Anda dapat menampilkan konten di dalam kotak yang sesuai dengan _style_ Starlight menggunakan komponen `<Card>`. -Bungkus beberapa _card_ dalam komponen `<CardGrid>` untuk menampilkan _card-card_ secara berdampingan ketika ada cukup ruang. - -`<Card>` memerlukan `title` dan secara opsional dapat ditambahkan atribut `icon` yang di-set dengan [nama salah satu icon bawaan Starlight](#semua-icon). - -```mdx -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="Cek sekarang">Konten menarik yang ingin Anda highlight.</Card> - -<CardGrid> - <Card title="Bintang" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Bulan" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> -``` - -Kode di atas akan menampilkan hasil sebagai berikut: - -<Card title="Cek sekarang">Konten menarik yang ingin Anda highlight.</Card> - -<CardGrid> - <Card title="Bintang" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Bulan" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> - -:::tip -Gunakan _card_ grid di halaman utama untuk menampilkan fitur-fitur utama proyek Anda. -Tambahkan atribut `stagger` untuk menggeser kolom kedua _card_ secara vertikal dan menambah daya tarik visual: - -```astro -<CardGrid stagger> - <!-- cards --> -</CardGrid> -``` - -::: - -### Link Cards - -Gunakan komponen `<LinkCard>` untuk menautkan ke berbagai halaman secara menonjol. - -`<LinkCard>` memerlukan atribut `title` dan [`href`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href). Anda juga dapat secara opsional menyertakan `description` singkat atau atribut tautan lain seperti `target`. - -Gabungkan beberapa komponen `<LinkCard>` dalam `<CardGrid>` untuk menampilkan kartu secara berdampingan ketika terdapat cukup ruang. - -```mdx -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -<LinkCard - title="Mengkustomisasi Starlight" - description="Pelajari cara membuat situs Starlight Anda sendiri dengan style, font, dan lainnya." - href="/id/guides/customization/" -/> - -<CardGrid> - <LinkCard title="Menulis Markdown" href="/id/guides/authoring-content/" /> - <LinkCard title="Komponen" href="/id/guides/components/" /> -</CardGrid> -``` - -Kode di atas akan menampilkan hasil sebagai berikut: - -import { LinkCard } from '@astrojs/starlight/components'; - -<LinkCard - title="Mengkustomisasi Starlight" - description="Pelajari cara membuat situs Starlight Anda sendiri dengan style, font, dan lainnya." - href="/id/guides/customization/" -/> - -<CardGrid> - <LinkCard title="Menulis Markdown" href="/id/guides/authoring-content/" /> - <LinkCard title="Komponen" href="/id/guides/components/" /> -</CardGrid> - -### Icon - -import { Icon } from '@astrojs/starlight/components'; -import IconsList from '~/components/icons-list.astro'; - -Starlight menyediakan sejumlah icon umum yang dapat Anda tampilkan dalam konten Anda menggunakan komponen `<Icon>`. - -Setiap `<Icon>` membutuhkan atribut [`name`](#semua-icon) dan dapat secara opsional menyertakan atribut `label`, `size`, dan `color`. - -```mdx -import { Icon } from '@astrojs/starlight/components'; - -<Icon name="star" color="goldenrod" size="2rem" /> -``` - -Kode di atas menghasilkan tampilan berikut di halaman: - -<Icon name="star" color="goldenrod" size="2rem" /> - -#### Semua Icon - -List dari semua icon-icon yang tersedia dapat dilihat di bawah sesuai dengan nama-nya masing-masing. Klik icon untuk menyalin kode komponen tersebut. - -<IconsList /> diff --git a/docs/src/content/docs/it/getting-started.mdx b/docs/src/content/docs/it/getting-started.mdx index b45f096d..2eab7a4f 100644 --- a/docs/src/content/docs/it/getting-started.mdx +++ b/docs/src/content/docs/it/getting-started.mdx @@ -91,7 +91,7 @@ Leggi di più sulla navigazione basata su file e sul supporto per i file MDX e M - **Configura:** scopri le opzioni comuni in ["Personalizzazione di Starlight"](/it/guides/customization/). - **Naviga:** configura la tua barra laterale con la guida ["Navigazione laterale"](/it/guides/sidebar/). -- **Componenti:** scopri schede incorporate, tabulazioni e altro nella guida ["Componenti"](/it/guides/components/). +- **Componenti:** scopri schede incorporate, tabulazioni e altro nella guida ["Componenti"](/it/components/using-components/). - **Distribuisci:** pubblica il tuo lavoro con la guida ["Distribuisci il tuo sito"](https://docs.astro.build/it/guides/deploy/) nella documentazione di Astro. ## Aggiorna Starlight diff --git a/docs/src/content/docs/it/guides/components.mdx b/docs/src/content/docs/it/guides/components.mdx deleted file mode 100644 index 00fe90f0..00000000 --- a/docs/src/content/docs/it/guides/components.mdx +++ /dev/null @@ -1,487 +0,0 @@ ---- -title: Componenti -description: Utilizzo dei componenti in MDX con Starlight. ---- - -I componenti permettono di riutilizzare un elemento UI o altro ripetutamente. -Degli esempi potrebbero essere delle sezioni di link o un video YouTube integrato. -Starlight supporta l'utilizzo di questi nei file [MDX](https://mdxjs.com/) e fornisce dei componenti per te già pronti. - -[Vedi di più sulla costruzione di componenti nella documentazione Astro](https://docs.astro.build/it/core-concepts/astro-components/). - -## Utilizzare un componente - -Puoi usare un componente importandolo nel tuo file MDX e poi visualizzarlo come un tag JSX. -Questi possono ricordare dei tag HTML ma iniziano con una maiuscola: - -```mdx ---- -# src/content/docs/example.mdx -title: Benvenuto nella mia documentazione ---- - -import SomeComponent from '../../components/SomeComponent.astro'; -import AnotherComponent from '../../components/AnotherComponent.astro'; - -<SomeComponent prop="qualcosa" /> - -<AnotherComponent> - I componenti possono avere **contenuti interni**. -</AnotherComponent> -``` - -Siccome Starlight è integrato con Astro, puoi aggiungere componenti costruiti con qualsiasi [UI framework supportato (React, Preact, Svelte, Vue, Solid, Lit, and Alpine)](https://docs.astro.build/it/core-concepts/framework-components/) nei tuoi file MDX. -Vedi di più su come [usare componenti in MDX](https://docs.astro.build/it/guides/markdown-content/#using-components-in-mdx) nella documentazione Astro. - -### Compatibilità con gli stili di Starlight - -Starlight applica stili predefiniti al tuo contenuto Markdown, ad esempio aggiungendo margini tra gli elementi. -Se questi stili entrano in conflitto con l'aspetto del tuo componente, imposta la classe `not-content` sul tuo componente per disabilitarli. - -```astro 'class="not-content"' ---- -// src/components/Example.astro ---- - -<div class="not-content"> - <p>Non influenzato dallo stile predefinito del contenuto di Starlight.</p> -</div> -``` - -## Componenti integrati - -Starlight fornisce dei componenti per casi comuni in una documentazione. -Questi sono disponibili nel pacchetto `@astrojs/starlight/components`. - -### Schede - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -Puoi rappresentare contenuti con un'interfaccia a schede con i componenti `<Tabs>` e `<TabItem>`. -Ogni `<TabItem>` deve avere un `label` per indicare la scheda corrispondente. -Usa l'attributo opzionale `icon` per includere una delle [icone integrate di Starlight](#tutte-le-icone) accanto all'etichetta. - -```mdx -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="Stelle" icon="star"> - Sirius, Vega, Betelgeuse - </TabItem> - <TabItem label="Lune" icon="moon"> - Io, Europa, Ganymede - </TabItem> -</Tabs> -``` - -Il codice sopra genera quanto segue nella pagina: - -<Tabs> - <TabItem label="Stelle" icon="star"> - Sirius, Vega, Betelgeuse - </TabItem> - <TabItem label="Lune" icon="moon"> - Io, Europa, Ganymede - </TabItem> -</Tabs> - -#### Schede sincronizzate - -Mantieni sincronizzati più gruppi di schede aggiungendo l'attributo `syncKey`. - -Tutti i componenti `<Tabs>` in una pagina con lo stesso valore `syncKey` mostreranno la stessa etichetta attiva. Questo permette al lettore di scegliere una volta (ad esempio, il proprio sistema operativo o gestore di pacchetti) e vedere la propria scelta riflessa in tutta la pagina. - -Per sincronizzare le schede correlate, aggiungi una proprietà `syncKey` identica a ciascun componente `<Tabs>` e assicurati che utilizzino tutte le stesse etichette `<TabItem>`: - -```mdx 'syncKey="constellations"' -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -_Alcune stelle:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem> - <TabItem label="Gemini">Pollux, Castor A, Castor B</TabItem> -</Tabs> - -_Alcuni esopianeti:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> -``` - -Il codice sopra genera quanto segue nella pagina: - -_Alcune stelle:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem> - <TabItem label="Gemini">Pollux, Castor A, Castor B</TabItem> -</Tabs> - -_Alcuni esopianeti:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> - -### Card - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -Puoi rappresentare i contenuti in un riquadro che rispecchia il tema Starlight usando il componente `<Card>`. -Racchiudi più card in `<CardGrid>` per visualizzarle fianco a fianco se c'è abbastanza spazio. - -Una `<Card>` necessita di `title` e può avere eventualmente un attributo `icon` impostato ad [una delle icone Starlight](#tutte-le-icone). - -```mdx -# src/content/docs/example.mdx - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="Guarda qui">Contenuti interessanti da evidenziare.</Card> - -<CardGrid> - <Card title="Stelle" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Lune" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> -``` - -Il codice sopra genera quanto segue nella pagina: - -<Card title="Guarda qui">Contenuti interessanti da evidenziare.</Card> - -<CardGrid> - <Card title="Stelle" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Lune" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> - -:::tip -Usa la griglia nella pagina principale per evidenziare le funzionalità chiave del progetto. -Aggiungi l'attributo `stagger` per rappresentare la seconda colonna più in basso per rendere il tutto più interessante: - -```astro -<CardGrid stagger> - <!-- cards --> -</CardGrid> -``` - -::: - -### Card con link - -Utilizza il componente `<LinkCard>` per collegare in modo visibile pagine diverse. - -Una `<LinkCard>` richiede un `title` e un attributo [`href`](https://developer.mozilla.org/it/docs/Web/HTML/Element/a#href). Facoltativamente puoi includere una breve `description` o altri attributi del collegamento come `target`. - -Raggruppa più componenti `<LinkCard>` in `<CardGrid>` per visualizzare le schede una accanto all'altra quando c'è spazio sufficiente. - -```mdx -# src/content/docs/example.mdx - -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -<LinkCard - title="Personalizzazione di Starlight" - description="Scopri come rendere il tuo sito Starlight unico con stili personalizzati, caratteri e altro." - href="/it/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Creazione di contenuti in Markdown" - href="/it/guides/authoring-content/" - /> - <LinkCard title="Componenti" href="/it/guides/components/" /> -</CardGrid> -``` - -Il codice sopra genera quanto segue nella pagina: - -import { LinkCard } from '@astrojs/starlight/components'; - -<LinkCard - title="Personalizzazione di Starlight" - description="Scopri come rendere il tuo sito Starlight unico con stili personalizzati, caratteri e altro." - href="/it/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Creazione di contenuti in Markdown" - href="/it/guides/authoring-content/" - /> - <LinkCard title="Componenti" href="/it/guides/components/" /> -</CardGrid> - -### Avvisi - -Gli avvisi sono utili per indicare contenuti secondari insieme ai contenuti principali. - -`<Aside>` può avere un `type` opzionale di `note` (il valore predefinito), `tip`, `caution` o `danger`. Impostando un attributo `title` si sovrascrive il titolo predefinito dell'avviso. - -````mdx -# src/content/docs/example.mdx - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>Un avviso predefinito senza un titolo personalizzato.</Aside> - -<Aside type="caution" title="Attenzione!"> - Un avviso *con* un titolo personalizzato. -</Aside> - -<Aside type="tip"> - -Altri contenuti sono supportati anche negli avvisi. - -```js -// Un pezzo di codice, per esempio. -``` - -</Aside> - -<Aside type="danger">Non dare la tua password a nessuno.</Aside> -```` - -Il codice sopra genera quanto segue nella pagina: - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>Un avviso di default senza un titolo personalizzato</Aside> - -<Aside type="caution" title="Attenzione!"> - Un avviso di cautela con un titolo personalizzato. -</Aside> - -<Aside type="tip"> - -Altri contenuti sono supportati anche negli avvisi. - -```js -// Un pezzo di codice, per esempio. -``` - -</Aside> - -<Aside type="danger">Non dare la tua password a nessuno.</Aside> - -Starlight fornisce anche una sintassi personalizzata per mostrare gli avvisi in Markdown e MDX come alternativa al componente `<Aside>`. -Consulta la guida [“Creazione di contenuti in Markdown”](/it/guides/authoring-content/#avvisi) per i dettagli sulla sintassi personalizzata. - -### Codice - -Utilizza il componente `<Code>` per visualizzare il codice sintatticamente evidenziato quando l'utilizzo di un [blocco di codice Markdown](/it/guides/authoring-content/#blocco-di-codice) non è possibile, ad esempio, per visualizzare dati provenienti da fonti esterne come file, database o API. - -Consulta la documentazione completa del componente ["Code Component" di Expressive Code](https://expressive-code.com/key-features/code-component/) per maggiori informazioni sulle proprietà supportate da `<Code>`. - -```mdx -# src/content/docs/example.mdx - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('Questo potrebbe provenire da un file o da un CMS!');`; -export const fileName = 'example.js'; -export const highlights = ['file', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> -``` - -Il codice sopra genera quanto segue nella pagina: - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('Questo potrebbe provenire da un file o da un CMS!');`; -export const fileName = 'example.js'; -export const highlights = ['file', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> - -#### Codice Importato - -Utilizza il [suffisso `?raw` dell'importazione con Vite](https://vitejs.dev/guide/assets#importing-asset-as-string) per importare qualsiasi file di codice come stringa. -Poi puoi passare questa stringa importata al componente `<Code>` per includerla nella tua pagina. - -```mdx title="src/content/docs/example.mdx" "?raw" -import { Code } from '@astrojs/starlight/components'; -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> -``` - -Il codice sopra genera quanto segue nella pagina: - -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> - -### Albero di File - -Utilizza il componente `<FileTree>` per visualizzare la struttura di una directory con icone dei file e directory chiudibili. - -Specifica la struttura dei tuoi file e directory con una [lista Markdown non ordinata](https://www.markdownguide.org/basic-syntax/#unordered-lists) all'interno di `<FileTree>`. -Crea una sottodirectory utilizzando una lista nidificata o aggiungi un `/` alla fine di un elemento della lista per renderlo una directory senza contenuto specifico. - -La seguente sintassi può essere utilizzata per personalizzare l'aspetto dell'albero dei file: - -- Evidenzia un file o una directory rendendo il suo nome in grassetto, ad esempio `**README.md**`. -- Aggiungi un commento a un file o a una directory aggiungendo più testo dopo il nome. -- Aggiungi file e directory segnaposto utilizzando `...` o `…` come nome. - -```mdx -# src/content/docs/example.mdx - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs un file **importante** -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> -``` - -Il codice sopra genera quanto segue nella pagina: - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs un file **importante** -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> - -### Passaggi - -Utilizza il componente `<Steps>` per stilizzare liste numerate di passaggi. -Questo è utile per guide passo-passo più complesse in cui ogni passo deve essere chiaramente evidenziato. - -Utilizza `<Steps>` in una lista ordinata standard di Markdown. -Tutta la solita sintassi Markdown è applicabile all'interno di `<Steps>`. - -````mdx title="src/content/docs/example.mdx" -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Importa il componente nel tuo file MDX: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Utilizza `<Steps>` intorno ai tuoi elementi della lista ordinata. - -</Steps> -```` - -Il codice sopra genera quanto segue nella pagina: - -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Importa il componente nel tuo file MDX: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Utilizza `<Steps>` intorno ai tuoi elementi della lista ordinata. - -</Steps> - -### Badge - -import { Badge } from '@astrojs/starlight/components'; - -Usa il componente `<Badge>` per mostrare piccole informazioni, come stati o etichette. - -Passa il contenuto che vuoi mostrare all'attributo `text` del componente `<Badge>`. - -Per impostazione predefinita, il badge utilizzerà il colore di accento del tema del tuo sito. Per utilizzare un colore di badge predefinito, imposta l'attributo `variant` su uno dei seguenti valori: `note` (blu), `tip` (viola), `danger` (rosso), `caution` (arancione), o `success` (verde). - -L'attributo `size` (predefinito: `small`) controlla la dimensione del testo del badge. Sono disponibili anche le opzioni `medium` e `large` per visualizzare un badge più grande. - -Per ulteriori personalizzazioni, usa altri attributi `<span>` come `class` o `style` con CSS personalizzato. - -```mdx title="src/content/docs/example.mdx" -import { Badge } from '@astrojs/starlight/components'; - -<Badge text="Nuovo" variant="tip" size="small" /> -<Badge text="Deprecato" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge - text="Personalizzato" - variant="success" - style={{ fontStyle: 'italic' }} -/> -``` - -Il codice sopra genera quanto segue nella pagina: - -<Badge text="Nuovo" variant="tip" size="small" /> -<Badge text="Deprecato" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge - text="Personalizzato" - variant="success" - style={{ fontStyle: 'italic' }} -/> - -### Icone - -import { Icon } from '@astrojs/starlight/components'; -import IconsList from '~/components/icons-list.astro'; - -Starlight fornisce una serie di icone comuni che puoi visualizzare nei tuoi contenuti utilizzando il componente `<Icon>`. - -Ogni `<Icon>` richiede un [`name`](#tutte-le-icone) e può facoltativamente includere un attributo `label`, `size` e `color`. -Gli attributi `size` e `color` possono essere utilizzati per regolare l'aspetto dell'icona utilizzando unità CSS e valori di colore. - -```mdx -# src/content/docs/example.mdx - -import { Icon } from '@astrojs/starlight/components'; - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> -``` - -Il codice sopra genera quanto segue nella pagina: - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> - -#### Tutte le icone - -Di seguito è riportato un elenco di tutte le icone disponibili con i nomi associati. Fare clic su un'icona per copiarne il codice componente. - -<IconsList /> diff --git a/docs/src/content/docs/ja/getting-started.mdx b/docs/src/content/docs/ja/getting-started.mdx index 9b2bcb1f..5be834a5 100644 --- a/docs/src/content/docs/ja/getting-started.mdx +++ b/docs/src/content/docs/ja/getting-started.mdx @@ -87,7 +87,7 @@ Starlightに新しいコンテンツを追加したり、既存のファイル - **設定:** [「Starlightのカスタマイズ」](/ja/guides/customization/)で、よく使われるオプションについて学びましょう。 - **ナビゲーション:** [「サイドバーのナビゲーション」](/ja/guides/sidebar/)ガイドで、サイドバーを設定しましょう。 -- **コンポーネント:** [「コンポーネント」](/ja/guides/components/)ガイドで、カードやタブなどの組み込みコンポーネントを確認しましょう。 +- **コンポーネント:** [「コンポーネント」](/ja/components/using-components/)ガイドで、カードやタブなどの組み込みコンポーネントを確認しましょう。 - **デプロイ:** Astroドキュメントの[「サイトのデプロイ」](https://docs.astro.build/ja/guides/deploy/)ガイドを参考に、あなたの作品を公開しましょう。 ## Starlightを更新する diff --git a/docs/src/content/docs/ja/guides/components.mdx b/docs/src/content/docs/ja/guides/components.mdx deleted file mode 100644 index f88d2ab1..00000000 --- a/docs/src/content/docs/ja/guides/components.mdx +++ /dev/null @@ -1,387 +0,0 @@ ---- -title: コンポーネント -description: StarlightにおけるMDXでのコンポーネントの利用。 ---- - -コンポーネントにより、UI やスタイリングの一部を一貫性を保って簡単に再利用できます。例として、リンクカードやYouTubeの埋め込みなどが考えられます。Starlightは[MDX](https://mdxjs.com/)ファイルでのコンポーネントの使用をサポートしており、すぐに使える一般的なコンポーネントもいくつか提供しています。 - -[コンポーネントの作り方について、詳しくはAstroドキュメントを参照してください](https://docs.astro.build/ja/core-concepts/astro-components/)。 - -## コンポーネントを使う - -コンポーネントは、MDXファイルにインポートしてJSXタグとしてレンダリングすることで使用できます。HTMLタグのように見えますが、`import`文の名前と同じ大文字で始まります。 - -```mdx ---- -# src/content/docs/example.mdx -title: Welcome to my docs ---- - -import SomeComponent from '../../components/SomeComponent.astro'; -import AnotherComponent from '../../components/AnotherComponent.astro'; - -<SomeComponent prop="何か" /> - -<AnotherComponent> - コンポーネントには**ネストされたコンテンツ**を含められます。 -</AnotherComponent> -``` - -StarlightはAstro製であるため、[サポート対象のUIフレームワーク（React、Preact、Svelte、Vue、Solid、Lit、Alpine）](https://docs.astro.build/ja/core-concepts/framework-components/)で作成されたコンポーネントであればMDXファイルで使用できます。[MDXでのコンポーネントの使用](https://docs.astro.build/ja/guides/markdown-content/#using-components-in-mdx)について、詳しくはAstroドキュメントを参照してください。 - -### Starlightのスタイルとの互換性 - -Starlightは、Markdownコンテンツにデフォルトのスタイルを適用します。たとえば、要素間にマージンを追加します。これらのスタイルがコンポーネントの見た目と競合する場合は、`not-content`クラスをコンポーネントに設定してスタイルを無効化してください。 - -```astro 'class="not-content"' ---- -// src/components/Example.astro ---- - -<div class="not-content"> - <p>Starlightのデフォルトのコンテンツスタイルに影響を受けません。</p> -</div> -``` - -## 組み込みのコンポーネント - -Starlightは、一般的なドキュメントのユースケースに対して組み込みのコンポーネントをいくつか提供しています。これらのコンポーネントは、`@astrojs/starlight/components`パッケージから利用できます。 - -### タブ - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -`<Tabs>`と`<TabItem>`コンポーネントを使用して、タブインターフェースを表示できます。各`<TabItem>`は、ユーザーに表示する`label`を必要とします。また、任意の`icon`属性を指定すると、ラベルの横に[Starlightの組み込みアイコン](#すべてのアイコン)を1つ含められます。 - -```mdx -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="恒星" icon="star"> - シリウス、ベガ、ペテルギウス - </TabItem> - <TabItem label="衛星" icon="moon"> - イオ、エウロパ、ガニメデ - </TabItem> -</Tabs> -``` - -上のコードは、ページに以下のタブを生成します。 - -<Tabs> - <TabItem label="恒星" icon="star"> - シリウス、ベガ、ペテルギウス - </TabItem> - <TabItem label="衛星" icon="moon"> - イオ、エウロパ、ガニメデ - </TabItem> -</Tabs> - -### カード - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -`<Card>`コンポーネントを使用すると、Starlightのスタイルに合わせたボックス内にコンテンツを表示できます。十分なスペースがある場合は、複数のカードを`<CardGrid>`コンポーネントで囲むことで、カードを並べて表示できます。 - -`<Card>`は`title`を必須とし、また任意で[Starlightの組み込みアイコンの1つ](#すべてのアイコン)を名前に設定した`icon`属性を含められます。 - -```mdx -# src/content/docs/example.mdx - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="確認しよう">強調したい興味深いコンテンツ。</Card> - -<CardGrid> - <Card title="恒星" icon="star"> - シリウス、ベガ、ペテルギウス - </Card> - <Card title="衛星" icon="moon"> - イオ、エウロパ、ガニメデ - </Card> -</CardGrid> -``` - -上のコードにより、ページに以下が生成されます。 - -<Card title="確認しよう">強調したい興味深いコンテンツ。</Card> - -<CardGrid> - <Card title="恒星" icon="star"> - シリウス、ベガ、ペテルギウス - </Card> - <Card title="衛星" icon="moon"> - イオ、エウロパ、ガニメデ - </Card> -</CardGrid> - -:::tip[ヒント] -プロジェクトの主要な機能を示すために、ホームページでカードグリッドを使いましょう。`stagger`属性を追加すると、カードの2番目の列を垂直方向にシフトして、視覚的な面白さを引き出します。 - -```astro -<CardGrid stagger> - <!-- カード --> -</CardGrid> -``` - -::: - -### リンクカード - -`<LinkCard>`を使用すると、他のページへのリンクを目立たせることができます。 - -`<LinkCard>`は`title`と[`href`](https://developer.mozilla.org/ja/docs/Web/HTML/Element/a#href)属性を必須とします。短い`description`や、`target`など他のリンク属性も指定できます。 - -十分なスペースがある場合、`<CardGrid>`により複数の`<LinkCard>`をグループ化して、カードを並べて表示できます。 - -```mdx -# src/content/docs/example.mdx - -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -<LinkCard - title="Starlightのカスタマイズ" - description="Starlightサイトをカスタマイズして、独自のスタイル、フォントなどを追加する方法について学びます。" - href="/ja/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Markdownでのコンテンツ作成" - href="/ja/guides/authoring-content/" - /> - <LinkCard title="コンポーネント" href="/ja/guides/components/" /> -</CardGrid> -``` - -上のコードにより、ページに以下が生成されます。 - -import { LinkCard } from '@astrojs/starlight/components'; - -<LinkCard - title="Starlightのカスタマイズ" - description="Starlightサイトをカスタマイズして、独自のスタイル、フォントなどを追加する方法について学びます。" - href="/ja/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Markdownでのコンテンツ作成" - href="/ja/guides/authoring-content/" - /> - <LinkCard title="コンポーネント" href="/ja/guides/components/" /> -</CardGrid> - -### 補足情報 - -「警告」や「吹き出し」とも呼ばれる補足情報（Asides）は、ページのメインコンテンツと並べて補助的な情報を表示するのに便利です。 - -`<Aside>`には、`note`（デフォルト）、`tip`、`caution`、`danger`のいずれかの`type`を任意で指定できます。`title`属性を設定すると、補足情報のデフォルトのタイトルが上書きされます。 - -````mdx -# src/content/docs/example.mdx - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>カスタムタイトルなしのデフォルトの補足情報。</Aside> - -<Aside type="caution" title="気を付けて！"> - カスタムタイトルを指定した警告用の補足情報。 -</Aside> - -<Aside type="tip"> - -その他のコンテンツも補足情報に含められます。 - -```js -// たとえばコードスニペット。 -``` - -</Aside> - -<Aside type="danger">パスワードは誰にも教えないでください。</Aside> -```` - -上のコードにより、ページに以下が生成されます。 - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>カスタムタイトルなしのデフォルトの補足情報。</Aside> - -<Aside type="caution" title="気を付けて！"> - カスタムタイトルを指定した警告用の補足情報。 -</Aside> - -<Aside type="tip"> - -その他のコンテンツも補足情報に含められます。 - -```js -// たとえばコードスニペット。 -``` - -</Aside> - -<Aside type="danger">パスワードは誰にも教えないでください。</Aside> - -Starlightは、`<Aside>`コンポーネントの代わりとして、MarkdownやMDXで補足情報をレンダリングするためのカスタム構文も提供しています。カスタム構文の詳細については、「[Markdownでのコンテンツ作成](/ja/guides/authoring-content/#補足情報)」ガイドを参照してください。 - -### コード - -ファイルやデータベース、APIなど、外部ソースからのデータをレンダリングするため[Markdownのコードブロック](/ja/guides/authoring-content/#コード)を使用できない場合に、`<Code>`コンポーネントを使用してシンタックスハイライトされたコードをレンダリングできます。 - -`<Code>`がサポートするプロパティの詳細については、[Expressive Codeの「Code Component」ドキュメント](https://expressive-code.com/key-features/code-component/)を参照してください。 - -```mdx -# src/content/docs/example.mdx - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('これはファイルやCMSから来た文字列!');`; -export const fileName = 'example.js'; -export const highlights = ['ファイル', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> -``` - -上のコードにより、ページに以下が生成されます。 - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('これはファイルやCMSから来た文字列!');`; -export const fileName = 'example.js'; -export const highlights = ['ファイル', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> - -#### インポートされたコード - -[Viteの`?raw`インポートサフィックス](https://ja.vitejs.dev/guide/assets.html#importing-asset-as-string)を使用して、任意のコードファイルを文字列としてインポートできます。 - -```mdx title="src/content/docs/example.mdx" "?raw" -import { Code } from '@astrojs/starlight/components'; -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> -``` - -上のコードにより、ページに以下が生成されます。 - -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> - -### ファイルツリー - -`<FileTree>`コンポーネントにより、ファイルアイコンと折りたたみ可能なサブディレクトリを使ってディレクトリの構造を表示できます。 - -`<FileTree>`内で[Markdownの順序なしリスト](https://www.markdownguide.org/basic-syntax/#unordered-lists)を使い、ファイルとディレクトリの構造を指定します。サブディレクトリを作成するにはリストをネストさせます。あるいは、リストアイテムの最後に`/`を追加することで、中身を指定しないディレクトリとしてレンダリングできます。 - -以下の構文により、ファイルツリーの見た目をカスタマイズできます。 - -- 名前を太字にして、ファイルやディレクトリをハイライトできます。たとえば`**README.md**`のようにします。 -- 名前の後ろにテキストを追加して、ファイルやディレクトリにコメントを追加できます。 -- `...`または`…`を名前として使用して、ファイルやディレクトリのプレースホルダーを追加できます。 - -```mdx -# src/content/docs/example.mdx - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs **重要**ファイル -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> -``` - -上のコードにより、ページに以下が生成されます。 - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs **重要**ファイル -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> - -### ステップ - -`<Steps>`コンポーネントにより、順序のあるタスクのリストをスタイリングできます。これは、各ステップを明確に強調する必要があるような、複雑なステップバイステップのガイドに便利です。 - -`<Steps>`でMarkdown標準の順序付きリストをラップします。`<Steps>`内では、通常のMarkdownの構文はすべて使用できます。 - -````mdx title="src/content/docs/example.mdx" -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. MDXファイルにコンポーネントをインポートします。 - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. 順序付きリストの各アイテムを`<Steps>`でラップします。 - -</Steps> -```` - -上のコードにより、ページに以下が生成されます。 - -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. MDXファイルにコンポーネントをインポートします。 - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. 順序付きリストの各アイテムを`<Steps>`でラップします。 - -</Steps> - -### アイコン - -import { Icon } from '@astrojs/starlight/components'; -import IconsList from '~/components/icons-list.astro'; - -Starlightは、`<Icon>`コンポーネントを通じてコンテンツ内に表示可能な、一般的なアイコンのセットを提供しています。 - -`<Icon>`は[`name`](#すべてのアイコン)を必須とし、任意で`label`、`size`、`color`属性を含められます。 - -```mdx -# src/content/docs/example.mdx - -import { Icon } from '@astrojs/starlight/components'; - -<Icon name="star" color="goldenrod" size="2rem" /> -``` - -上のコードにより、ページに以下が生成されます。 - -<Icon name="star" color="goldenrod" size="2rem" /> - -#### すべてのアイコン - -以下に、利用可能なすべてのアイコンとその名前を示します。アイコンをクリックすると、対応するコンポーネントのコードをコピーできます。 - -<IconsList /> diff --git a/docs/src/content/docs/ko/getting-started.mdx b/docs/src/content/docs/ko/getting-started.mdx index 69a93162..4d2b8845 100644 --- a/docs/src/content/docs/ko/getting-started.mdx +++ b/docs/src/content/docs/ko/getting-started.mdx @@ -93,7 +93,7 @@ Starlight는 새로운 콘텐츠를 추가하거나 기존 파일을 가져올 - **구성:** [“Starlight 사용자 정의”](/ko/guides/customization/)에서 일반적인 옵션에 대해 알아보세요. - **탐색:** ["사이드바 탐색"](/ko/guides/sidebar/) 가이드를 사용하여 사이드바를 설정하세요. -- **컴포넌트:** ["컴포넌트"](/ko/guides/components/) 가이드에서 내장된 카드 컴포넌트, 탭 컴포넌트 등을 찾아보세요. +- **컴포넌트:** ["컴포넌트"](/ko/components/using-components/) 가이드에서 내장된 카드 컴포넌트, 탭 컴포넌트 등을 찾아보세요. - **배포:** Astro 문서의 [“사이트 배포”](https://docs.astro.build/ko/guides/deploy/) 가이드를 사용하여 작업을 게시하세요. ## Starlight 업데이트 diff --git a/docs/src/content/docs/ko/guides/components.mdx b/docs/src/content/docs/ko/guides/components.mdx deleted file mode 100644 index f4f5479f..00000000 --- a/docs/src/content/docs/ko/guides/components.mdx +++ /dev/null @@ -1,511 +0,0 @@ ---- -title: 컴포넌트 -description: Starlight를 이용해 MDX에서 컴포넌트 사용하기. ---- - -컴포넌트를 사용하면 쉽고 일관되게 UI 조각이나 스타일을 재사용할 수 있습니다. -링크 카드나 YouTube 삽입 등을 예로 들 수 있습니다. -Starlight는 [MDX](https://mdxjs.com/) 파일에서 컴포넌트 사용을 지원하며 사용할 수 있는 몇 가지 공통 컴포넌트를 제공합니다. - -[Astro 문서에서 컴포넌트 구축에 대해 자세히 알아보세요](https://docs.astro.build/ko/core-concepts/astro-components/). - -## 컴포넌트 사용 - -MDX 파일에서 컴포넌트를 가져온 다음 JSX 태그로 렌더링하여 사용할 수 있습니다. -이는 HTML 태그처럼 보이지만 `import` 문에 있는 이름과 일치하는 대문자로 시작합니다. - -```mdx ---- -# src/content/docs/example.mdx -title: 내 문서에 오신 것을 환영합니다 ---- - -import SomeComponent from '~/components/SomeComponent.astro'; -import AnotherComponent from '~/components/AnotherComponent.astro'; - -<SomeComponent prop="어떤 값" /> - -<AnotherComponent> - 컴포넌트에는 **중첩된 콘텐츠**가 포함될 수도 있습니다. -</AnotherComponent> -``` - -Starlight는 Astro로 구동되므로 [지원되는 UI 프레임워크(React, Preact, Svelte, Vue, Solid, Lit 및 Alpine)](https://docs.astro.build/ko/core-concepts/framework-components/)로 빌드된 컴포넌트를 MDX 파일에 추가할 수 있습니다. -Astro 문서에서 [MDX에서 컴포넌트 사용](https://docs.astro.build/ko/guides/markdown-content/#using-comComponents-in-mdx)에 대해 자세히 알아보세요. - -### Starlight 스타일과의 호환성 - -Starlight는 요소 사이에 여백을 추가하는 등 Markdown 콘텐츠에 기본 스타일을 적용합니다. -이러한 스타일이 컴포넌트의 모양과 충돌하는 경우 컴포넌트에 `not-content` 클래스를 추가하여 비활성화하세요. - -```astro 'class="not-content"' ---- -// src/components/Example.astro ---- - -<div class="not-content"> - <p>Starlight의 기본 콘텐츠 스타일에 영향을 받지 않습니다.</p> -</div> -``` - -## 내장된 컴포넌트 - -Starlight는 일반적인 문서 사용 사례를 위한 몇 가지 내장 컴포넌트를 제공합니다. -이러한 컴포넌트는 `@astrojs/starlight/components` 패키지를 통해 사용할 수 있습니다. - -### 탭 - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -`<Tabs>` 및 `<TabItem>` 컴포넌트를 사용하여 탭 인터페이스를 표시할 수 있습니다. -각 `<TabItem>`은 사용자에게 보여줄 `label`을 반드시 포함해야합니다. -label 옆에 [Starlight 내장 아이콘](#모든-아이콘) 중 하나를 포함하려면 선택적 `icon` 속성을 사용하세요. - -```mdx -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="별" icon="star"> - 시리우스, 베가, 베텔게우스 - </TabItem> - <TabItem label="달" icon="moon"> - 이오, 유로파, 가니메데 - </TabItem> -</Tabs> -``` - -위 코드는 페이지에 아래와 같은 탭을 생성합니다. - -<Tabs> - <TabItem label="별" icon="star"> - 시리우스, 베가, 베텔게우스 - </TabItem> - <TabItem label="달" icon="moon"> - 이오, 유로파, 가니메데 - </TabItem> -</Tabs> - -#### 동기화된 탭 - -`syncKey` 속성을 추가하여 여러 탭 그룹을 동기화된 상태로 유지합니다. - -`syncKey` 값이 같은 모든 `<Tabs>`는 동일한 활성 라벨을 표시합니다. 이렇게 하면 독자가 운영 체제나 패키지 관리자 등을 한 번 선택하면 페이지 탐색 간 선택한 내용이 유지되는 것을 확인할 수 있습니다. - -관련 탭을 동기화하려면 각 `<Tabs>` 컴포넌트에 동일한 `syncKey` 속성을 추가하고 모두 동일한 `<TabItem>` 라벨을 사용하는지 확인하세요. - -```mdx 'syncKey="별자리"' -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -_별:_ - -<Tabs syncKey="별자리"> - <TabItem label="오리온자리">벨라트릭스, 리겔, 베텔게우스</TabItem> - <TabItem label="쌍둥이자리">폴룩스, 캐스터 A, 캐스터 B</TabItem> -</Tabs> - -_외계 행성:_ - -<Tabs syncKey="별자리"> - <TabItem label="오리온자리">HD 34445 b, 글리제 179 b, Wasp-82 b</TabItem> - <TabItem label="쌍둥이자리">폴룩스 b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> -``` - -위 코드는 페이지에 다음을 생성합니다. - -_별:_ - -<Tabs syncKey="별자리"> - <TabItem label="오리온자리">벨라트릭스, 리겔, 베텔게우스</TabItem> - <TabItem label="쌍둥이자리">폴룩스, 캐스터 A, 캐스터 B</TabItem> -</Tabs> - -_외계 행성:_ - -<Tabs syncKey="별자리"> - <TabItem label="오리온자리">HD 34445 b, 글리제 179 b, Wasp-82 b</TabItem> - <TabItem label="쌍둥이자리">폴룩스 b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> - -### 카드 - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -`<Card>` 컴포넌트를 사용하면 Starlight 스타일의 상자에 콘텐츠를 표시할 수 있습니다. -공간이 충분할 때 카드를 나란히 표시하려면 `<CardGrid>` 컴포넌트로 여러 카드를 감싸세요. - -`<Card>` 컴포넌트에는 `title` 속성이 반드시 필요하며 선택적으로 [Starlight 내장 아이콘 중 하나](#모든-아이콘)의 이름으로 설정된 `icon` 속성을 포함할 수 있습니다. - -```mdx -# src/content/docs/example.mdx - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="확인">강조하고 싶은 흥미로운 콘텐츠.</Card> - -<CardGrid> - <Card title="별" icon="star"> - 시리우스, 베가, 베텔게우스 - </Card> - <Card title="달" icon="moon"> - 이오, 유로파, 가니메데 - </Card> -</CardGrid> -``` - -위 코드는 페이지에 아래와 같은 요소들을 생성합니다. - -<Card title="확인">강조하고 싶은 흥미로운 콘텐츠.</Card> - -<CardGrid> - <Card title="별" icon="star"> - 시리우스, 베가, 베텔게우스 - </Card> - <Card title="달" icon="moon"> - 이오, 유로파, 가니메데 - </Card> -</CardGrid> - -:::tip - -홈 페이지에서 프로젝트의 주요 기능을 보여주기 위해 카드 그리드를 사용하세요. -카드의 두 번째 열을 수직으로 이동시켜 시각적 흥미를 더하려면 `stagger` 속성을 추가하세요. - -```astro -<CardGrid stagger> - <!-- 카드 --> -</CardGrid> -``` - -::: - -### 링크 카드 - -다른 페이지로 이동하는 눈에 띄는 링크를 만들기 위해 `<LinkCard>` 컴포넌트를 사용하세요. - -`<LinkCard>` 컴포넌트에는 `title`과 [`href`](https://developer.mozilla.org/ko/docs/Web/HTML/Element/a#attr-href) 속성이 필요합니다. 짧은 `description`이나 `target`과 같은 기타 링크 속성을 선택적으로 포함할 수 있습니다. - -공간이 충분할 때, 카드를 나란히 표시하기 위해 여러 `<LinkCard>` 컴포넌트를 `<CardGrid>`에 그룹화하세요. - -```mdx -# src/content/docs/example.mdx - -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -<LinkCard - title="Starlight 사용자 정의" - description="사용자 정의 스타일, 글꼴 등을 사용하여 나만의 Starlight 사이트를 만드는 방법을 알아보세요." - href="/ko/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="마크다운으로 콘텐츠 작성" - href="/ko/guides/authoring-content/" - /> - <LinkCard title="컴포넌트" href="/ko/guides/components/" /> -</CardGrid> -``` - -위 코드는 페이지에 아래와 같은 요소들을 생성합니다. - -import { LinkCard } from '@astrojs/starlight/components'; - -<LinkCard - title="Starlight 사용자 정의" - description="사용자 정의 스타일, 글꼴 등을 사용하여 나만의 Starlight 사이트를 만드는 방법을 알아보세요." - href="/ko/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="마크다운으로 콘텐츠 작성" - href="/ko/guides/authoring-content/" - /> - <LinkCard title="컴포넌트" href="/ko/guides/components/" /> -</CardGrid> - -### 링크 버튼 - -시각적으로 구분되는 콜투액션 링크에는 `<LinkButton>` 컴포넌트를 사용합니다. -링크 버튼은 가장 관련성이 높거나 실행 가능한 콘텐츠로 사용자를 안내하는 데 유용하며 랜딩 페이지에서 자주 사용됩니다 - -`<LinkButton>`에는 [`href`](https://developer.mozilla.org/ko/docs/Web/HTML/Element/a#href) 속성이 필요하며, 'target'과 같은 다른 링크 속성을 선택적으로 허용합니다. - -`icon` 속성을 [Starlight 내장 아이콘 중 하나](#모든-아이콘)의 이름으로 설정하여 텍스트 옆에 아이콘을 포함할 수 있습니다. -텍스트 앞에 아이콘을 배치하기 위해 `iconPlacement` 속성을 `start`로 설정할 수 있습니다 (기본값은 `end`). - -`primary` (기본값), `secondary`, `minimal`로 설정할 수 있는 `variant` 속성을 사용하여 링크 버튼의 모양을 사용자 정의합니다. - -```mdx -# src/content/docs/example.mdx - -import { LinkButton } from '@astrojs/starlight/components'; - -<LinkButton href="/ko/getting-started/">시작하기</LinkButton> -<LinkButton href="https://docs.astro.build" variant="secondary" icon="external"> - 관련: Astro -</LinkButton> -``` - -위의 코드는 페이지에 다음과 같은 내용을 생성합니다: - -import { LinkButton } from '@astrojs/starlight/components'; - -<LinkButton href="/ko/getting-started/">시작하기</LinkButton> -<LinkButton href="https://docs.astro.build" variant="secondary" icon="external"> - 관련: Astro -</LinkButton> - -### 주석 - -“권고” 또는 “콜아웃”이라고도 하는 '주석'은 페이지의 기본 콘텐츠 옆에 보조 정보를 표시하는 데 유용합니다. - -`<Aside>`에는 `note` (기본값), `tip`, `caution` 또는 `danger` 등 선택적인 `type`이 있을 수 있습니다. `title` 속성을 설정하면 주석의 기본 제목을 재정의합니다. - -````mdx -# src/content/docs/example.mdx - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>제목을 설정하지 않은 기본 주석입니다.</Aside> - -<Aside type="caution" title="주의!"> - 제목이 설정된 경고 주석입니다. -</Aside> - -<Aside type="tip"> - -주석에서는 다른 콘텐츠도 지원됩니다. - -```js -// 코드 조각의 예시입니다. -``` - -</Aside> - -<Aside type="danger">여러분의 비밀번호를 누구에게도 알려주지 마세요.</Aside> -```` - -위 코드는 페이지에 다음을 생성합니다. - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>제목을 설정하지 않은 기본 주석입니다.</Aside> - -<Aside type="caution" title="주의!"> - 제목이 설정된 경고 주석입니다. -</Aside> - -<Aside type="tip"> - -주석에서는 다른 콘텐츠도 지원됩니다. - -```js -// 코드 조각의 예시입니다. -``` - -</Aside> - -<Aside type="danger">여러분의 비밀번호를 누구에게도 알려주지 마세요.</Aside> - -Starlight는 `<Aside>` 컴포넌트 대신 Markdown 및 MDX에서 Aside를 렌더링하기 위한 사용자 정의 구문도 제공합니다. -사용자 정의 구문에 대한 자세한 내용은 [“마크다운으로 콘텐츠 작성”](/ko/guides/authoring-content/#주석) 가이드를 참조하세요. - -### 코드 - -예를 들어 파일, 데이터베이스 또는 API와 같은 외부 소스에서 오는 데이터를 렌더링하기 위해 [Markdown 코드 블록](/ko/guides/authoring-content/#코드-블록)을 사용할 수 없는 경우 `<Code>` 컴포넌트를 사용하여 구문 강조 코드를 렌더링합니다. - -`<Code>`가 지원하는 props에 대한 자세한 내용은 [Expressive Code “Code Component” 문서](https://expressive-code.com/key-features/code-component/)를 참조하세요. - -```mdx -# src/content/docs/example.mdx - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('This could come from a file or CMS!');`; -export const fileName = 'example.js'; -export const highlights = ['file', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> -``` - -위 코드는 페이지에 다음을 생성합니다. - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('This could come from a file or CMS!');`; -export const fileName = 'example.js'; -export const highlights = ['file', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> - -#### 가져온 코드 - -[Vite의 `?raw` 가져오기 접미사](https://vitejs.dev/guide/assets#importing-asset-as-string)를 사용하여 코드 파일을 문자열로 가져옵니다. 그런 다음 가져온 문자열을 `<Code>` 컴포넌트에 전달하여 페이지에 포함할 수 있습니다. - -```mdx title="src/content/docs/example.mdx" "?raw" -import { Code } from '@astrojs/starlight/components'; -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> -``` - -위 코드는 페이지에 다음을 생성합니다. - -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> - -### 파일 트리 - -`<FileTree>` 컴포넌트를 사용하면 파일 아이콘과 축소 가능한 하위 디렉터리가 있는 디렉터리 구조를 표시할 수 있습니다. - -`<FileTree>`에서 [순서가 지정되지 않은 Markdown 목록](https://www.markdownguide.org/basic-syntax/#unordered-lists)을 사용하여 파일 및 디렉터리의 구조를 지정하세요. -중첩된 목록을 사용하여 하위 디렉터리를 생성하거나 목록 항목 끝에 `/`를 추가하여 특정 내용이 없는 디렉터리로 렌더링합니다. - -다음 구문을 사용하여 파일 트리의 모양을 사용자 정의할 수 있습니다. - -- 이름을 굵게 표시하여 파일이나 디렉터리를 강조 표시합니다. 예: `**README.md**`. -- 이름 뒤에 더 많은 텍스트를 추가하여 파일이나 디렉터리에 설명을 추가합니다. -- `...` 또는 `…`을 이름으로 사용하여 자리 표시자 파일과 디렉터리를 추가합니다. - -```mdx -# src/content/docs/example.mdx - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs **중요** 파일 -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> -``` - -위 코드는 페이지에 다음을 생성합니다. - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs **중요** 파일 -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> - -### 단계 - -`<Steps>` 컴포넌트를 사용하여 번호가 매겨진 작업 목록의 스타일을 지정합니다. -이는 각 단계를 명확하게 강조해야 하는 보다 복잡한 단계별 가이드에 유용합니다. - -표준 Markdown 정렬 목록을 `<Steps>`로 묶습니다. -모든 일반적인 Markdown 구문은 `<Steps>` 내에서 적용 가능합니다. - -````mdx title="src/content/docs/example.mdx" -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. 컴포넌트를 MDX 파일로 가져옵니다. - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. 순서가 매겨진 목록 항목을 `<Steps>`로 묶습니다. - -</Steps> -```` - -위 코드는 페이지에 다음을 생성합니다. - -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. 컴포넌트를 MDX 파일로 가져옵니다. - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. 순서가 매겨진 목록 항목을 `<Steps>`로 묶습니다. - -</Steps> - -### 배지 - -import { Badge } from '@astrojs/starlight/components'; - -상태나 라벨과 같은 작은 정보를 표시하려면 `<Badge>` 컴포넌트를 사용하세요. - -표시하려는 콘텐츠를 `<Badge>` 컴포넌트의 `text` 속성에 전달하세요. - -기본적으로 배지는 사이트의 테마 강조 색상을 사용합니다. 내장 배지 색상을 사용하려면 `variant` 속성의 값을 `note` (파란색), `tip` (보라색), `danger` (빨간색), `caution` (주황색), 'success'(녹색) 중 하나로 설정하세요. - -`size` 속성 (기본값: `small`)은 배지의 텍스트 크기를 제어합니다. 더 큰 배지를 표시하기 위해 `medium` 및 `large` 옵션도 사용할 수 있습니다. - -맞춤 설정이 더 필요하다면 사용자 정의 CSS와 함께 `class` 또는 `style`과 같은 다른 `<span>` 속성을 사용하세요. - -```mdx title="src/content/docs/example.mdx" -import { Badge } from '@astrojs/starlight/components'; - -<Badge text="New" variant="tip" size="small" /> -<Badge text="Deprecated" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Custom" variant="success" style={{ fontStyle: 'italic' }} /> -``` - -위의 코드는 페이지에 다음을 생성합니다. - -<Badge text="New" variant="tip" size="small" /> -<Badge text="Deprecated" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Custom" variant="success" style={{ fontStyle: 'italic' }} /> - -### 아이콘 - -import { Icon } from '@astrojs/starlight/components'; -import IconsList from '~/components/icons-list.astro'; - -Starlight는 `<Icon>` 컴포넌트를 사용하여 콘텐츠에 표시할 수 있는 공통 아이콘 세트를 제공합니다. - -각 `<Icon>`에는 [`name`](#모든-아이콘)이 필요하며 스크린 리더에 컨텍스트를 제공하기 위해 선택적으로 `label`을 포함할 수 있습니다. -CSS 단위와 색상 값을 사용하여 아이콘의 모양을 조정하는 데 `size` 및 `color` 속성을 사용할 수 있습니다. - -```mdx -# src/content/docs/example.mdx - -import { Icon } from '@astrojs/starlight/components'; - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> -``` - -위 코드는 페이지에 다음을 생성합니다. - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> - -#### 모든 아이콘 - -사용 가능한 모든 아이콘 목록이 관련 이름과 함께 아래에 표시됩니다. 아이콘을 클릭하면 해당 컴포넌트의 코드를 복사할 수 있습니다. - -<IconsList /> diff --git a/docs/src/content/docs/pt-br/getting-started.mdx b/docs/src/content/docs/pt-br/getting-started.mdx index 00cf8aa0..f7de6014 100644 --- a/docs/src/content/docs/pt-br/getting-started.mdx +++ b/docs/src/content/docs/pt-br/getting-started.mdx @@ -91,7 +91,7 @@ Leia mais sobre roteamento baseado em arquivos e suporte para arquivos MDX e Mar - **Configurar:** Descubra opções comuns em ["Customizando Starlight"](/pt-br/guides/customization/). - **Navegar:** Configure a barra lateral com o guia [“Barra lateral de navegação”](/pt-br/guides/sidebar/). -- **Componentes:** Conheça os cartões, abas e outros componentes integrados no guia [“Componentes”](/pt-br/guides/components/). +- **Componentes:** Conheça os cartões, abas e outros componentes integrados no guia [“Componentes”](/pt-br/components/using-components/). - **Deploy:** Publique seu projeto com o guia [“Deploy do seu site Astro”](https://docs.astro.build/pt-br/guides/deploy/) na documentação do Astro. ## Atualizando Starlight diff --git a/docs/src/content/docs/pt-br/guides/components.mdx b/docs/src/content/docs/pt-br/guides/components.mdx deleted file mode 100644 index e372139c..00000000 --- a/docs/src/content/docs/pt-br/guides/components.mdx +++ /dev/null @@ -1,479 +0,0 @@ ---- -title: Componentes -description: Utilizando componentes no MDX com Starlight. ---- - -Componentes te permitem facilmente reutilizar pedaços da UI ou estilizar consistentemente. -Alguns exemplos são um cartão de link ou um embed do YouTube. -Starlight suporta o uso de componentes em arquivos [MDX](https://mdxjs.com/) e providencia alguns components comuns para você utilizar. - -[Aprenda mais sobre como construir componentes na documentação do Astro](https://docs.astro.build/pt-br/core-concepts/astro-components/). - -## Utilizando um componente - -Você pode utilizar um componente ao importá-lo em seu arquivo MDX e então renderizá-lo como uma tag JSX. -Elas se parecem com tags HTML porém começam com uma letra maiúscula correspondente ao nome na sua declaração `import`: - -```mdx ---- -# src/content/docs/exemplo.mdx -title: Bem-vindo a minha documentação ---- - -import AlgumComponente from '../../components/AlgumComponente.astro'; -import OutroComponente from '../../components/OutroComponente.astro'; - -<AlgumComponente prop="algo" /> - -<OutroComponente> - Componentes também podem conter **conteúdo aninhado**. -</OutroComponente> -``` - -Já que Starlight é feito com Astro, você pode adicionar suporte para componentes feitos com qualquer [framework de UI suportado (React, Preact, Svelte, Vue, Solid, Lit e Alpine)](https://docs.astro.build/pt-br/core-concepts/framework-components/) em seus arquivos MDX. -Aprenda mais sobre como [utilizar componentes no MDX](https://docs.astro.build/pt-br/guides/markdown-content/#usando-componentes-no-mdx) na documentação do Astro. - -### Compatibilidade com os estilos do Starlight - -Starlight aplica estilos padrões para seu conteúdo Markdown, como por exemplo, adicionando margem entre elementos. -Se esses estilos conflitam com a aparência do seu componente, defina a classe `not-content` no seu componente para desabilitá-los. - -```astro 'class="not-content"' ---- -// src/components/Exemplo.astro ---- - -<div class="not-content"> - <p>Não é impactado pelos estilos padrões de conteúdo do Starlight.</p> -</div> -``` - -## Componentes integrados - -Starlight providencia alguns componentes integrados para casos de uso comuns em documentações. -Esses componentes estão disponíveis através do pacote `@astrojs/starlight/components`. - -### Abas - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -Você pode mostrar uma interface com abas utilizando os componentes `<Tabs>` e `<TabItem>`. -Cada `<TabItem>` tem que ter uma `label` para mostrar aos usuários. -Use o atributo opcional `icon` para incluir um dos [ícones predefinidos do Starlight](#todos-os-ícones) ao lado da label. - -```mdx -# src/content/docs/exemplo.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="Estrelas" icon="star"> - Sirius, Vega, Betelgeuse - </TabItem> - <TabItem label="Luas" icon="moon"> - Io, Europa, Ganimedes - </TabItem> -</Tabs> -``` - -O código acima gera as seguintes abas na página: - -<Tabs> - <TabItem label="Estrelas" icon="star"> - Sirius, Vega, Betelgeuse - </TabItem> - <TabItem label="Luas" icon="moon"> - Io, Europa, Ganimedes - </TabItem> -</Tabs> - -#### Abas sincronizadas - -Mantenha vários grupos de abas sincronizados adicionando o atributo `syncKey`. - -Todas as `<Tabs>` em uma página com o mesmo valor `syncKey` exibirão a mesma label ativa. Isso permite que o leitor escolha uma vez (por exemplo, o sistema operacional ou o gerenciador de pacotes) e veja essa escolha refletida em toda a página. - -Para sincronizar as abas relacionadas, adicione uma propriedade `syncKey` idêntica a cada componente `<Tabs>` e certifique-se de que todos eles usem as mesmas labels de `<TabItem>`: - -```mdx 'syncKey="constelações"' -# src/content/docs/exemplo.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -_Algumas estrelas:_ - -<Tabs syncKey="constelações"> - <TabItem label="Orion">Bellatrix, Rígel, Betelgeuse</TabItem> - <TabItem label="Gemini">Pólux, Castor A, Castor B</TabItem> -</Tabs> - -_Alguns exoplanetas:_ - -<Tabs syncKey="constelações"> - <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Gemini">Pólux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> -``` - -O código acima gera o seguinte na página: - -_Algumas estrelas:_ - -<Tabs syncKey="constelações"> - <TabItem label="Orion">Bellatrix, Rígel, Betelgeuse</TabItem> - <TabItem label="Gemini">Pólux, Castor A, Castor B</TabItem> -</Tabs> - -_Alguns exoplanetas:_ - -<Tabs syncKey="constelações"> - <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Gemini">Pólux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> - -### Cartões - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -Você pode mostrar conteúdo em uma caixa seguindo os estilos do Starlight utilizando o componente `<Card>`. -Coloque múltiplos cartões no componente `<CardGrid>` para mostrar cartões lado a lado quando houver espaço suficiente. - -Um `<Card>` precisa de um `title` e pode opcionalmente incluir o atributo `icon` para definir o nome de um dos [ícones integrados do Starlight](#todos-os-ícones). - -```mdx -# src/content/docs/exemplo.mdx - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="Veja isso">Conteúdo interessante que você quer destacar.</Card> - -<CardGrid> - <Card title="Estrelas" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Luas" icon="moon"> - Io, Europa, Ganimedes - </Card> -</CardGrid> -``` - -O código acima gera o seguinte na página: - -<Card title="Veja isso">Conteúdo interessante que você quer destacar.</Card> - -<CardGrid> - <Card title="Estrelas" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Luas" icon="moon"> - Io, Europa, Ganimedes - </Card> -</CardGrid> - -:::tip -Utilize um grid de cartões na sua página inicial para mostrar as principais funcionalidades do seu projeto. -Adicione o atributo `stagger` para mover a segunda coluna de cartões verticalmente para adicionar interesse visual: - -```astro -<CardGrid stagger> - <!-- cartões --> -</CardGrid> -``` - -::: - -### Cartões de Link - -Utilize o componente `<LinkCard>` para fazer um link proeminente para outras páginas. - -Um `<LinkCard>` precisa de um `title` e um atributo [`href`](https://developer.mozilla.org/pt-BR/docs/Web/HTML/Element/a#attr-href). Você pode opcionalmente incluir uma pequena `description` ou outros atributos de link como `target`. - -Agrupe múltiplos componentes `<LinkCard>` em um `<CardGrid>` para mostrar cartões lado a lado quando houver espaço suficiente. - -```mdx -# src/content/docs/exemplo.mdx - -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -<LinkCard - title="Customizando Starlight" - description="Aprenda como fazer seu site Starlight único com estilos customizados, fontes e mais." - href="/pt-br/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Escrevendo Markdown" - href="/pt-br/guides/authoring-content/" - /> - <LinkCard title="Componentes" href="/pt-br/guides/components/" /> -</CardGrid> -``` - -O código acima gera o seguinte na página: - -import { LinkCard } from '@astrojs/starlight/components'; - -<LinkCard - title="Customizando Starlight" - description="Aprenda como fazer seu site Starlight único com estilos customizados, fontes e mais." - href="/pt-br/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Escrevendo Markdown" - href="/pt-br/guides/authoring-content/" - /> - <LinkCard title="Componentes" href="/pt-br/guides/components/" /> -</CardGrid> - -### Asides - -Asides (também conhecidos como "advertências" ou "frases de destaque") são úteis para exibir informações secundárias ao lado do conteúdo principal de uma página. - -Um `<Aside>` pode ter um `type` opcional de `note` (o padrão), `tip`, `caution` ou `danger`. A definição de um atributo `title` substitui o título padrão do aside. - -````mdx -# src/content/docs/exemplo.mdx - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>Um aside padrão sem um título personalizado.</Aside> - -<Aside type="caution" title="Cuidado!"> - Um aside de aviso *com* um título personalizado. -</Aside> - -<Aside type="tip"> - -Outros conteúdos também são compatíveis com asides. - -```js -// Um trecho de código, por exemplo. -``` - -</Aside> - -<Aside type="danger">Não forneça sua senha a ninguém.</Aside> -```` - -O código acima gera o seguinte na página: - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>Um aside padrão sem um título personalizado.</Aside> - -<Aside type="caution" title="Cuidado!"> - Um aside de aviso *com* um título personalizado. -</Aside> - -<Aside type="tip"> - -Outros conteúdos também são compatíveis com asides. - -```js -// Um trecho de código, por exemplo. -``` - -</Aside> - -<Aside type="danger">Não forneça sua senha a ninguém.</Aside> - -O Starlight também fornece uma sintaxe personalizada para renderizar asides em Markdown e MDX como uma alternativa ao componente `<Aside>`. -Consulte o guia ["Escrevendo Conteúdo em Markdown"](/pt-br/guides/authoring-content/#asides) para obter detalhes sobre a sintaxe personalizada. - -### Código - -Use o componente `<Code>` para renderizar código com syntax highlighting quando não for possível usar um [bloco de código Markdown](/pt-br/guides/authoring-content/#blocos-de-código), por exemplo, para renderizar dados provenientes de fontes externas, como arquivos, bancos de dados ou APIs. - -Consulte a [documentação do "Componente de código" do Expressive Code](https://expressive-code.com/key-features/code-component/) para obter detalhes completos sobre as propriedades suportadas pelo `<Code>`. - -```mdx -# src/content/docs/exemplo.mdx - -import { Code } from '@astrojs/starlight/components'; - -export const codigoExemplo = `console.log('Isso pode vir de um arquivo ou CMS!');`; -export const nomeArquivo = 'exemplo.js'; -export const destaques = ['arquivo', 'CMS']; - -<Code code={codigoExemplo} lang="js" title={nomeArquivo} mark={destaques} /> -``` - -O código acima gera o seguinte na página: - -import { Code } from '@astrojs/starlight/components'; - -export const codigoExemplo = `console.log('Isso pode vir de um arquivo ou CMS!');`; -export const nomeArquivo = 'exemplo.js'; -export const destaques = ['arquivo', 'CMS']; - -<Code code={codigoExemplo} lang="js" title={nomeArquivo} mark={destaques} /> - -#### Código importado - -Use o [sufixo de importação `?raw` do Vite](https://vitejs.dev/guide/assets#importing-asset-as-string) para importar qualquer arquivo de código como uma string. -Em seguida, você pode passar essa string importada para o componente `<Code>` para incluí-la em sua página. - -```mdx title="src/content/docs/exemplo.mdx" "?raw" -import { Code } from '@astrojs/starlight/components'; -import codigoImportado from '/src/env.d.ts?raw'; - -<Code code={codigoImportado} lang="ts" title="src/env.d.ts" /> -``` - -O código acima gera o seguinte na página: - -import codigoImportado from '/src/env.d.ts?raw'; - -<Code code={codigoImportado} lang="ts" title="src/env.d.ts" /> - -### Árvore de arquivos - -Use o componente `<FileTree>` para exibir a estrutura de um diretório com ícones de arquivos e subdiretórios colapsáveis. - -Especifique a estrutura de seus arquivos e diretórios com uma [lista Markdown não ordenada](https://www.markdownguide.org/basic-syntax/#unordered-lists) dentro de `<FileTree>`. -Crie um subdiretório usando uma lista aninhada ou adicione uma `/` ao final de um item da lista para renderizá-lo como um diretório sem conteúdo específico. - -A sintaxe a seguir pode ser usada para personalizar a aparência da árvore de arquivos: - -- Destaque um arquivo ou diretório tornando seu nome em negrito, por exemplo, `**README.md**`. -- Adicione um comentário a um arquivo ou diretório acrescentando mais texto após o nome. -- Adicione arquivos e diretórios placeholder usando `...` ou `…` como nome. - -```mdx -# src/content/docs/exemplo.mdx - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs um arquivo **importante** -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> -``` - -O código acima gera o seguinte na página: - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs um arquivo **importante** -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> - -### Etapas - -Use o componente `<Steps>` para estilizar listas numeradas de tarefas. -Isso é útil para guias passo a passo mais complexos, em que cada etapa precisa ser claramente destacada. - -Envolva uma lista ordenada padrão do Markdown com o `<Steps>`. -Toda a sintaxe usual do Markdown é aplicável dentro de `<Steps>`. - -````mdx title="src/content/docs/exemplo.mdx" -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Importe o componente em seu arquivo MDX: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Envolva seus itens de lista ordenada com `<Steps>`. - -</Steps> -```` - -O código acima gera o seguinte na página: - -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Importe o componente em seu arquivo MDX: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Envolva seus itens de lista ordenada com `<Steps>`. - -</Steps> - -### Emblemas - -import { Badge } from '@astrojs/starlight/components'; - -Use o componente `<Badge>` para exibir pequenas informações, como status ou etiquetas. - -Passe o conteúdo que deseja exibir para o atributo `text` do componente `<Badge>`. - -Por padrão, o emblema usará a cor de destaque do tema do seu site. Para usar uma cor de emblema incorporada, defina o atributo `variant` com um dos seguintes valores: `note` (azul), `tip` (roxo), `danger` (vermelho), `caution` (laranja) ou `success` (verde). - -O atributo `size` (padrão: `small`) controla o tamanho do texto do emblema. As opções `medium` e `large` também estão disponíveis para exibir um emblema maior. - -Para personalização adicional, use outros atributos da tag `<span>` como `class` ou `style` com CSS personalizado. - -```mdx title="src/content/docs/example.mdx" -import { Badge } from '@astrojs/starlight/components'; - -<Badge text="Novo" variant="tip" size="small" /> -<Badge text="Obsoleto" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Personalizado" variant="success" style={{ fontStyle: 'italic' }} /> -``` - -O código acima gera o seguinte conteúdo na página: - -<Badge text="Novo" variant="tip" size="small" /> -<Badge text="Obsoleto" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Personalizado" variant="success" style={{ fontStyle: 'italic' }} /> - -### Ícone - -import { Icon } from '@astrojs/starlight/components'; -import IconsList from '~/components/icons-list.astro'; - -Starlight providencia um conjunto comum de ícones que você pode mostrar em seu conteúdo utilizando o componente `<Icon>`. - -Cada `<Icon>` requer um [`name`](#todos-os-ícones) e pode opcionalmente incluir um atributo `label` para prover contexto aos leitores de tela. -Os atributos `size` e `color` podem ser utilizados para ajustar a aparência do ícone usando unidades CSS e valores de cores. - -```mdx -# src/content/docs/exemplo.mdx - -import { Icon } from '@astrojs/starlight/components'; - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> -``` - -O código acima gera o seguinte na página: - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> - -#### Todos os ícones - -Uma lista de todos os ícones disponíveis é mostrada abaixo com seus nomes associados. Clique em um ícone para copiar o código do componente dele. - -<IconsList /> diff --git a/docs/src/content/docs/pt-pt/getting-started.mdx b/docs/src/content/docs/pt-pt/getting-started.mdx index 7270cbf5..557cda2e 100644 --- a/docs/src/content/docs/pt-pt/getting-started.mdx +++ b/docs/src/content/docs/pt-pt/getting-started.mdx @@ -91,7 +91,7 @@ Saiba mais acerca de _routing_ baseado em ficheiros e suporte para ficheiros MDX - **Configurar:** Descubra opções comuns em ["Customização do Starlight"](/pt-pt/guides/customization/). - **Navegar:** Configure a barra lateral com o guia [“Barra lateral de navegação”](/pt-pt/guides/sidebar/). -- **Componentes:** Conheça os cartões, separadores e outros componentes integrados no guia [“Componentes”](/pt-pt/guides/components/). +- **Componentes:** Conheça os cartões, separadores e outros componentes integrados no guia [“Componentes”](/pt-pt/components/using-components/). - **Deploy:** Publique o seu projeto com a ajuda do guia [“Deploy do seu site Astro”](https://docs.astro.build/pt-br/guides/deploy/) na documentação do Astro. ## Atualizar o Starlight diff --git a/docs/src/content/docs/reference/icons.mdx b/docs/src/content/docs/reference/icons.mdx new file mode 100644 index 00000000..9a4e2727 --- /dev/null +++ b/docs/src/content/docs/reference/icons.mdx @@ -0,0 +1,19 @@ +--- +title: Icons Reference +description: An overview of all the icons available in Starlight. +--- + +Starlight provides a set of built-in icons that you can display in your content using the `<Icon>` component. + +## Use icons + +Icons can be displayed using the [`<Icon>`](/components/icons/) component. +They are also often used in other components, such as [cards](/components/cards/) or settings like [hero actions](/reference/frontmatter/#hero). + +## All icons + +A list of all available icons is shown below with their associated names. Click an icon to copy its name to your clipboard. + +import IconsList from '~/components/icons-list.astro'; + +<IconsList /> diff --git a/docs/src/content/docs/ru/getting-started.mdx b/docs/src/content/docs/ru/getting-started.mdx index bcdc7fdc..a1aa364c 100644 --- a/docs/src/content/docs/ru/getting-started.mdx +++ b/docs/src/content/docs/ru/getting-started.mdx @@ -91,7 +91,7 @@ Starlight готов к созданию нового контента или к - **Настройка:** Узнайте об общих опциях в главе [Настройка Starlight](/ru/guides/customization/). - **Навигация.** Настройте боковую панель с помощью руководства [Навигация по боковой панели](/ru/guides/sidebar/). -- **Компоненты.** Узнайте о встроенных карточках, вкладках и многом другом в руководстве [Компоненты](/ru/guides/components/). +- **Компоненты.** Узнайте о встроенных карточках, вкладках и многом другом в руководстве [Компоненты](/ru/components/using-components/). - **Развёртывание.** Опубликуйте свою работу с помощью руководства [Развёртывание вашего сайта](https://docs.astro.build/ru/guides/deploy/) в документации Astro. ## Обновление Starlight diff --git a/docs/src/content/docs/ru/guides/components.mdx b/docs/src/content/docs/ru/guides/components.mdx deleted file mode 100644 index a26b5202..00000000 --- a/docs/src/content/docs/ru/guides/components.mdx +++ /dev/null @@ -1,511 +0,0 @@ ---- -title: Компоненты -description: Использование компонентов в MDX со Starlight. ---- - -Компоненты позволяют легко и последовательно переиспользовать часть пользовательского интерфейса или стиля. -Примерами могут служить карточки-ссылки или встраиваемые ролики YouTube. -Starlight поддерживает использование компонентов в файлах [MDX](https://mdxjs.com/) и предоставляет некоторые общие компоненты для вашего использования. - -[Узнайте больше о создании компонентов в документации Astro](https://docs.astro.build/ru/core-concepts/astro-components/). - -## Использование компонента - -Вы можете использовать компонент, импортировав его в ваш файл MDX, а затем отобразив его как тег JSX. -Они выглядят как HTML-теги, но начинаются с заглавной буквы, соответствующей имени в вашем операторе `import`: - -```mdx ---- -# src/content/docs/example.mdx -title: Добро пожаловать в мою документацию ---- - -import SomeComponent from '../../components/SomeComponent.astro'; -import AnotherComponent from '../../components/AnotherComponent.astro'; - -<SomeComponent prop="something" /> - -<AnotherComponent> - Компоненты могут содержать **вложенное содержимое**. -</AnotherComponent> -``` - -Поскольку Starlight работает на базе Astro, вы можете использовать в своих файлах MDX любые компоненты, созданные на [поддерживаемом UI-фреймворке (React, Preact, Svelte, Vue, Solid, Lit и Alpine)](https://docs.astro.build/ru/core-concepts/framework-components/). -Узнайте больше об [использовании компонентов в MDX](https://docs.astro.build/ru/guides/markdown-content/#использование-компонентов-в-mdx) в документации Astro. - -### Совместимость со стилями Starlight - -Starlight применяет стандартные стили к вашему содержимому в формате Markdown, например, добавляет отступ между элементами. -Если эти стили конфликтуют с внешним видом вашего компонента, установите класс `not-content` для вашего компонента, чтобы отключить их. - -```astro 'class="not-content"' ---- -// src/components/Example.astro ---- - -<div class="not-content"> - <p>Стандартные стили Starlight не применены.</p> -</div> -``` - -## Встроенные компоненты - -Starlight предоставляет встроенные компоненты для частых случаев, нужных в документации. -Эти компоненты доступны из пакета `@astrojs/starlight/components`. - -### Вкладки - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -Вы можете отобразить интерфейс с вкладками, используя компоненты `<Tabs>` и `<TabItem>`. -Каждый компонент `<TabItem>` должен иметь `label` для отображения пользователям. -Используйте дополнительный атрибут `icon`, чтобы включить одну из [встроенных иконок Starlight](#все-иконки) рядом с меткой. - -```mdx -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="Звёзды" icon="star"> - Сириус, Вега, Бетельгейзе - </TabItem> - <TabItem label="Луны" icon="moon"> - Ио, Европа, Ганимед - </TabItem> -</Tabs> -``` - -Вышеуказанный код сформирует следующие вкладки: - -<Tabs> - <TabItem label="Звёзды" icon="star"> - Сириус, Вега, Бетельгейзе - </TabItem> - <TabItem label="Луны" icon="moon"> - Ио, Европа, Ганимед - </TabItem> -</Tabs> - -#### Синхронизированные вкладки - -Синхронизируйте несколько групп вкладок, добавив атрибут `syncKey`. - -Все `<Tabs>` с одинаковым значением `syncKey` будут отображать одну и ту же активную метку. Это позволит вашему читателю выбрать один раз (например, операционную систему или менеджер пакетов), и видеть, что их выбор сохраняется при переходе по страницам. - -Чтобы синхронизировать связанные вкладки, добавьте идентичное свойство `syncKey` к каждому компоненту `<Tabs>` и убедитесь, что все они используют одни и те же метки `<TabItem>`: - -```mdx 'syncKey="constellations"' -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -_Некоторые звёзды:_ - -<Tabs syncKey="constellations"> - <TabItem label="Орион">Беллатрикс, Ригель, Бетельгейзе</TabItem> - <TabItem label="Близнецы">Поллукс, Кастор А, Кастор Б</TabItem> -</Tabs> - -_Некоторые экзопланеты:_ - -<Tabs syncKey="constellations"> - <TabItem label="Орион">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Близнецы">Поллукс b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> -``` - -Вышеуказанный код сформирует следующий HTML: - -_Некоторые звёзды:_ - -<Tabs syncKey="constellations"> - <TabItem label="Орион">Беллатрикс, Ригель, Бетельгейзе</TabItem> - <TabItem label="Близнецы">Поллукс, Кастор А, Кастор Б</TabItem> -</Tabs> - -_Некоторые экзопланеты:_ - -<Tabs syncKey="constellations"> - <TabItem label="Орион">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Близнецы">Поллукс b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> - -### Карточки - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -Вы можете отображать контент в блоке, со стилями Starlight, используя компонент `<Card>`. -Оберните несколько карточек в компонент `<CardGrid>`, чтобы отображать карточки рядом, когда есть достаточно места. - -`<Card>` требует `title` и может дополнительно включать атрибут `icon`, установленный как название [одной из встроенных иконок Starlight](#все-иконки). - -```mdx -# src/content/docs/example.mdx - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="Зацени">Интересный контент, который вы хотите подсветить.</Card> - -<CardGrid> - <Card title="Звёзды" icon="star"> - Сириус, Вега, Бетельгейзе - </Card> - <Card title="Луны" icon="moon"> - Ио, Европа, Ганимед - </Card> -</CardGrid> -``` - -Вышеуказанный код сформирует следующий HTML: - -<Card title="Зацени">Интересный контент, который вы хотите подсветить.</Card> - -<CardGrid> - <Card title="Звёзды" icon="star"> - Сириус, Вега, Бетельгейзе - </Card> - <Card title="Луны" icon="moon"> - Ио, Европа, Ганимед - </Card> -</CardGrid> - -:::tip -Используйте сетку карточек на вашей домашней странице для отображения ключевых функций вашего проекта. -Добавьте атрибут `stagger`, чтобы сместить вторую колонку карточек по вертикали и добавить визуальный интерес: - -```astro -<CardGrid stagger> - <!-- cards --> -</CardGrid> -``` - -::: - -### Карточки-ссылки - -Используйте компонент `<LinkCard>` для создания заметных ссылок на разные страницы. - -`<LinkCard>` требует атрибута `title` и атрибута [`href`](https://developer.mozilla.org/ru/docs/Web/HTML/Element/a#href). По желанию вы можете добавить краткое `description` или другие атрибуты ссылки, такие как `target`. - -Группируйте несколько компонентов `<LinkCard>` в `<CardGrid>`, чтобы отображать карточки рядом, когда есть достаточно места. - -```mdx -# src/content/docs/example.mdx - -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -<LinkCard - title="Кастомизация Starlight" - description="Узнайте, как сделать ваш сайт на Starlight уникальным с вашим логотипом, шрифтами, дизайном главной страницы и многим другим" - href="/ru/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Создание контента в Markdown" - href="/ru/guides/authoring-content/" - /> - <LinkCard title="Компоненты" href="/ru/guides/components/" /> -</CardGrid> -``` - -Вышеуказанный код сформирует следующий HTML: - -import { LinkCard } from '@astrojs/starlight/components'; - -<LinkCard - title="Кастомизация Starlight" - description="Узнайте, как сделать ваш сайт на Starlight уникальным с вашим логотипом, шрифтами, дизайном главной страницы и многим другим" - href="/ru/guides/customization/" -/> - -<CardGrid> - <LinkCard - title="Создание контента в Markdown" - href="/ru/guides/authoring-content/" - /> - <LinkCard title="Компоненты" href="/ru/guides/components/" /> -</CardGrid> - -### Кнопки-ссылки - -Используйте компонент `<LinkButton>` для визуального выделения ссылок, призывающих к действию. -Кнопка-ссылка полезна для направления пользователей к наиболее релевантному или действующему контенту и часто используется на целевых страницах. - -`<LinkButton>` требует обязательного атрибута [`href`](https://developer.mozilla.org/ru/docs/Web/HTML/Element/a#href) и по желанию принимает другие атрибуты ссылки, такие как `target`. - -Атрибут `icon` может содержать имя [одной из встроенных иконок Starlight](#все-иконки), чтобы включить иконку рядом с текстом. -Атрибут `iconPlacement` можно использовать для размещения иконки перед текстом, задав ему значение `start` (по умолчанию `end`). - -Настройте внешний вид кнопки-ссылки с помощью атрибута `variant`, который может быть установлен в значение `primary` (по умолчанию), `secondary` или `minimal`. - -```mdx -# src/content/docs/example.mdx - -import { LinkButton } from '@astrojs/starlight/components'; - -<LinkButton href="/ru/getting-started/">Первые шаги</LinkButton> -<LinkButton href="https://docs.astro.build" variant="secondary" icon="external"> - Похожие: Astro -</LinkButton> -``` - -Вышеуказанный код сформирует следующий HTML: - -import { LinkButton } from '@astrojs/starlight/components'; - -<LinkButton href="/ru/getting-started/">Первые шаги</LinkButton> -<LinkButton href="https://docs.astro.build" variant="secondary" icon="external"> - Похожие: Astro -</LinkButton> - -### Вставки - -Вставки полезны для отображения второстепенной информации рядом с основным содержанием страницы. - -У `<Aside>` может быть необязательный атрибут `type` со значением `note`, `tip`, `caution`, или `danger` (по умолчанию — `note`). Установка атрибута `title` отменяет заголовок, установленный по умолчанию. - -````mdx -# src/content/docs/example.mdx - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>Стандартная вставка без пользовательского заголовка.</Aside> - -<Aside type="caution" title="Осторожно!"> - Вставка предупреждения *с* пользовательским заголовком. -</Aside> - -<Aside type="tip" title="Совет"> - -Другой контент также поддерживается. - -```js -// Например, фрагмент кода. -``` - -</Aside> - -<Aside type="danger">Никому не сообщайте свой пароль.</Aside> -```` - -Вышеуказанный код сформирует следующий HTML: - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>Стандартная вставка без пользовательского заголовка.</Aside> - -<Aside type="caution" title="Осторожно!"> - Вставка предупреждения *с* пользовательским заголовком. -</Aside> - -<Aside type="tip" title="Совет"> - -Другой контент также поддерживается. - -```js -// Например, фрагмент кода. -``` - -</Aside> - -<Aside type="danger">Никому не сообщайте свой пароль.</Aside> - -Starlight также предоставляет собственный синтаксис для рендеринга в Markdown и MDX в качестве альтернативы компоненту `<Aside>`. -Подробную информацию о пользовательском синтаксисе см. в руководстве [Создание контента в Markdown](/ru/guides/authoring-content/#вставки). - -### Код - -Используйте компонент `<Code>` для рендеринга выделенного синтаксиса кода, когда использование [блока кода Markdown](/ru/guides/authoring-content/#блоки-кода) невозможно, например, для рендеринга данных, поступающих из внешних источников: файлов, баз данных или API. - -См. главу [Компонент кода](https://expressive-code.com/key-features/code-component/) в документации Expressive Code для получения полной информации о параметрах, которые поддерживает `<Code>`. - -```mdx -# src/content/docs/example.mdx - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('Это может быть файл или CMS.!');`; -export const fileName = 'example.js'; -export const highlights = ['файл', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> -``` - -Вышеуказанный код сформирует следующий HTML: - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('Это может быть файл или CMS.!');`; -export const fileName = 'example.js'; -export const highlights = ['файл', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> - -#### Импортированный код - -Используйте [суффикс импорта Vite `?raw`](https://vitejs.dev/guide/assets#importing-asset-as-string), чтобы импортировать любой файл кода в виде строки. -Затем вы можете передать эту импортированную строку компоненту `<Code>`, чтобы включить её на свою страницу. - -```mdx title="src/content/docs/example.mdx" "?raw" -import { Code } from '@astrojs/starlight/components'; -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> -``` - -Вышеуказанный код сформирует следующий HTML: - -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> - -### Дерево файлов - -Используйте компонент `<FileTree>` для отображения структуры каталога с иконками файлов и сворачиваемыми подкаталогами. - -Укажите структуру ваших файлов и каталогов с помощью [неупорядоченного списка Markdown](https://www.markdownguide.org/basic-syntax/#unordered-lists) внутри `<FileTree>`. -Создайте подкаталог с помощью вложенного списка или добавьте `/` в конец элемента списка, чтобы отобразить его как каталог без определённого содержимого. - -Для настройки внешнего вида дерева файлов можно использовать следующий синтаксис: - -- Выделите файл или каталог, сделав его имя жирным, например: `**README.md**`. -- Добавьте комментарий к файлу или каталогу, добавив дополнительный текст после имени. -- Добавьте заглушки файлов и каталогов, используя в качестве имени либо `...`, либо `…`. - -```mdx -# src/content/docs/example.mdx - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs — **важный** файл -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> -``` - -Вышеуказанный код сформирует следующий HTML: - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs — **важный** файл -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> - -### Шаги - -Используйте компонент `<Steps>` для стилизации нумерованных списков задач. -Это удобно для сложных пошаговых руководств, где каждый шаг должен быть чётко выделен. - -Оберните `<Steps>` вокруг стандартного упорядоченного списка Markdown. -Внутри `<Steps>` применим весь обычный синтаксис Markdown. - -````mdx title="src/content/docs/example.mdx" -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Импортируйте компонент в свой MDX-файл: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Оберните `<Steps>` вокруг элементов упорядоченного списка. - -</Steps> -```` - -Вышеуказанный код сформирует следующий HTML: - -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Импортируйте компонент в свой MDX-файл: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Оберните `<Steps>` вокруг элементов упорядоченного списка. - -</Steps> - -### Значки - -import { Badge } from '@astrojs/starlight/components'; - -Используйте компонент `<Badge>` для отображения небольших фрагментов информации, таких как статус или ярлыки. - -Передайте содержимое, которое вы хотите отобразить, в атрибут `text` компонента `<Badge>`. - -По умолчанию значок будет использовать акцентный цвет темы вашего сайта. Чтобы использовать встроенный цвет значка, установите атрибут `variant` в одно из следующих значений: `note` (синий), `tip` (фиолетовый), `danger` (красный), `caution` (оранжевый), или `success` (зелёный). - -Атрибут `size` (по умолчанию: `small`) управляет размером текста значка. Для отображения значка большего размера также доступны опции `medium` и `large`. - -Для дальнейшей настройки используйте другие атрибуты `<span>`, такие как `class` или `style`, с помощью пользовательского CSS. - -```mdx title="src/content/docs/example.mdx" -import { Badge } from '@astrojs/starlight/components'; - -<Badge text="Новое" variant="tip" size="small" /> -<Badge text="Устарело" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Свой текст" variant="success" style={{ fontStyle: 'italic' }} /> -``` - -Вышеуказанный код сформирует следующий HTML: - -<Badge text="Новое" variant="tip" size="small" /> -<Badge text="Устарело" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Свой текст" variant="success" style={{ fontStyle: 'italic' }} /> - -### Иконки - -import { Icon } from '@astrojs/starlight/components'; -import IconsList from '~/components/icons-list.astro'; - -Starlight предоставляет набор общих иконок, которые вы можете отображать в своем контенте, используя компонент `<Icon>`. - -Каждый `<Icon>` требует атрибут [`name`](#все-иконки) и по желанию может включать атрибут `label`, для предоставления контекста программам чтения с экрана. -Атрибуты `size` и `color` могут быть использованы для оформления иконки с помощью CSS. - -```mdx -# src/content/docs/example.mdx - -import { Icon } from '@astrojs/starlight/components'; - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> -``` - -Вышеуказанный код сформирует следующий HTML: - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> - -#### Все иконки - -Список всех доступных иконок показан ниже с их соответствующими именами. Кликните по значку, чтобы скопировать код компонента для него. - -<IconsList /> diff --git a/docs/src/content/docs/tr/getting-started.mdx b/docs/src/content/docs/tr/getting-started.mdx index 30bc8920..fe0f9884 100644 --- a/docs/src/content/docs/tr/getting-started.mdx +++ b/docs/src/content/docs/tr/getting-started.mdx @@ -91,7 +91,7 @@ Dosya bazlı gezinim ve MDX ile Markdoc dosya desteği hakkında daha fazlası i - **Yapılandır:** [“Starlight'ı özelleştirmek”](/tr/guides/customization/) rehberinde ortak ayarlar hakkında öğren. - **Gezinme:** [“Kenar Çubuğu Gezinimi”](/tr/guides/sidebar/) rehberi ile kenar çubuğunu ayarla. -- **Bileşenler:** [“Bileşenler”](/tr/guides/components/) rehberinde hazır yapılmış kartlar, tablar ve daha fazlasını keşfet. +- **Bileşenler:** [“Bileşenler”](/tr/components/using-components/) rehberinde hazır yapılmış kartlar, tablar ve daha fazlasını keşfet. - **Yayına al:** Astro dokümantayonu içerisindeki [“Siteni yayına al”](https://docs.astro.build/en/guides/deploy/) rehberi ile çalışmanı yayınla. ## Starlight'ı Güncelleme diff --git a/docs/src/content/docs/tr/guides/components.mdx b/docs/src/content/docs/tr/guides/components.mdx deleted file mode 100644 index ada09744..00000000 --- a/docs/src/content/docs/tr/guides/components.mdx +++ /dev/null @@ -1,437 +0,0 @@ ---- -title: Bileşenler -description: Starlight ile MDX'te bileşenlerin kullanımı. ---- - -Bileşenler bir arayüz parçasını kolaylıkla tekrar tekrar kullanmanıza ve tutarlı bir şekilde stillendirmenize olanak sağlar. -Bağlantı kartı ya da bir Youtube yerleştirmesi örnek olarak verilebilir. -Starlight [MDX](https://mdxjs.com/) dosyaları içerisindeki bileşenlerin kullanılmasını destekler ve bazı ortak bileşenleri kullanımınıza sunar. - -[Astro dokümantasyonunda bileşen oluşturma hakkında daha fazla bilgi edinin](https://docs.astro.build/en/core-concepts/astro-components/). - -## Bileşen Kullanımı - -Bir bileşeni MDX dosyanıza dahil ederek kullanabilir ve sonrasında JSX etiketi olarak oluşturabilirsiniz. -HTML etiketleri gibi görünür ancak ilk harfi büyük olarak ismi uyan `import` ifadesidir: - -```mdx ---- -# src/content/docs/index.mdx -title: Dokümantasyonuma hoşgeldiniz. ---- - -import SomeComponent from '../../components/SomeComponent.astro'; -import AnotherComponent from '../../components/AnotherComponent.astro'; - -<SomeComponent prop="birşey" /> - -<AnotherComponent> - Bileşenler ayrıca **içe yerleştirilmiş içerik** barındırabilir. -</AnotherComponent> -``` - -Starlight'ın Astro'dan aldığı güç sayesinde, MDX dosyalarınız içerisinde [desteklenen herhangi bir arayüz çerçevesi ile (React, Preact, Svelte, Vue, Solid, Lit, ve Alpine)](https://docs.astro.build/en/core-concepts/framework-components/) oluşturulmuş bileşenlerinizi destekleyebilirsiniz. -Astro dokümantasyonunda [MDX içerisinde bileşen kullanmak](https://docs.astro.build/en/guides/markdown-content/#using-components-in-mdx) hakkında daha fazlasını öğrenin. - -### Starlight stilleri ile uyumluluk - -Starlight Markdown içeriklerinize varsayılan stillendirmeyi uygular, örneğin elemanlar arasına marjin ekler. -Bu stiller bileşeninizin görünümü ile çakışıyorsa, bileşeninizde stili etkisiz kılmak için `not-content` sınıfını bileşeninize ekleyin. - -```astro ---- -// src/components/Example.astro ---- - -<div class="not-content"> - <p>Starlight'ın varsayılan içerik stillendirmesinden etkilenmez.</p> -</div> -``` - -## Yerleşik Bileşenler - -Starlight bazı yerleşik bileşenleri ortak dokümantasyon ihtiyaçları için sunar. -Bu bileşenler `@astrojs/starlight/components` paketinde mevcuttur. - -### Sekmeler - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -`<Tabs>` ve `<TabItem>` bileşenlerini kullanarak sekmeli arayüz gösterebilirsiniz. -Her `<TabItem>` bileşenini kullanıcılara göstermek için `label` sahibi olması zorunludur. -[Starlight’ın yerleşik ikonlarından](#tüm-i̇konlar) birini, etiketin yanında kalması için zorunlu olmayan `icon` niteliğini kullanın. - -```mdx -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="Yıldızlar" icon="star"> - Sirius, Vega, Betelgeuse - </TabItem> - <TabItem label="Uydular" icon="moon"> - Io, Europa, Ganymede - </TabItem> -</Tabs> -``` - -Yukarıdaki kod, sayfa üzerinde aşağıdaki gibi sekmeler oluşturur: - -<Tabs> - <TabItem label="Yıldızlar" icon="star"> - Sirius, Vega, Betelgeuse - </TabItem> - <TabItem label="Uydular" icon="moon"> - Io, Europa, Ganymede - </TabItem> -</Tabs> - -#### Senkronize Sekmeler - -`syncKey` niteliği ekleyerek çoklu sekme gruplarınızı senkronize edin. - -Sayfadaki aynı `syncKey` değerine sahip tüm `<Tabs>` bileşenleri aynı etkin etiketi görüntüler. Bu, okuyucunuza bir kez seçme (örneğin okuyucunuzun işletim sistemi ya da paket yöneticisi) ve sayfa boyunca yansıyan seçimi görmesine olanak tanır. - -İlişkili sekmeleri senkronize etmek için, her `<Tabs>` bileşenine özdeş `syncKey` niteliği ekleyin ve hepsinin aynı `<TabItems>` etiketi kullandığına emin olun: - -```mdx 'syncKey="constellations"' -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -_Bazı yıldızlar:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem> - <TabItem label="Gemini">Pollux, Castor A, Castor B</TabItem> -</Tabs> - -_Bazı ötegezegenler:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> -``` - -Yukarıdaki kod, sayfa üzerinde aşağıdaki gibi çıktı oluşturur: - -_Bazı yıldızlar:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem> - <TabItem label="Gemini">Pollux, Castor A, Castor B</TabItem> -</Tabs> - -_Bazı ötegezegenler:_ - -<Tabs syncKey="constellations"> - <TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> - -### Kartlar - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -`<Card>` bileşenini kullanarak Starlight'ın stiline uyan kutu içerisinde yer alan içeriği gösterebilirsiniz. -Birden fazla kartı `<CardGrid>` bileşeni içinde, yeteri kadar boşluk olduğu zaman kartları yan yana sıralı olarak göstermek için sarmalayın. - -`<Card>` bileşeni `title` değerine ihtiyaç duyar ve opsiyonel olarak [Starlight'ın kurulu ikonlarından birinin](#tüm-i̇konlar) ismini taşıyan `icon` özelliğini içerebilir. - -```mdx -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="Buna bir bakın.">Vurgulamak istediğin ilgi çekici içerik</Card> - -<CardGrid> - <Card title="Yıldızlar" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Uydular" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> -``` - -Yukarıdaki kod, sayfa üzerinde aşağıdaki gibi çıktı oluşturur: - -<Card title="Buna bir bakın.">Vurgulamak istediğin ilgi çekici içerik</Card> - -<CardGrid> - <Card title="Yıldızlar" icon="star"> - Sirius, Vega, Betelgeuse - </Card> - <Card title="Uydular" icon="moon"> - Io, Europa, Ganymede - </Card> -</CardGrid> - -:::tip -Projenizin kilit özelliklerini göstermek için anasayfanızda kart kılavuzunu kullanın. -`stagger` niteliğini ikinci sütunun kartlarını düşey eksenli olarak sıralamak ve görsel açıdan ilgi çekmek için ekleyin: - -```astro -<CardGrid stagger> - <!-- kartlar --> -</CardGrid> -``` - -::: - -### Bağlantı kartları - -Belirgin olarak farklı sayfalara bağlantı eklemek için `<LinkCard>` bileşenini kullanın. - -`<LinkCard>` `title` değerine ve [`href`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#href) özelliğine ihtiyaç duyar. İsteğe bağlı olarak `description` ya da `target` gibi bağlantı özelliklerini ekleyebilirsiniz. - -Birden fazla `<LinkCard>` bileşeninizi, yeterince boşluk olduğunda yan yana olacak şekilde göstermek için `<CardGrid>` içerisinde gruplayın. - -```mdx -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -<LinkCard - title="Starlight'ı Özelleştirmek" - description="Starlight sitenizi kendi özel stiliniz, yazı karakteriniz ve daha fazlası ile nasıl oluşturacağınızı öğrenin." - href="/tr/guides/customization/" -/> - -<CardGrid> - <LinkCard title="Markdown Oluşturmak" href="/tr/guides/authoring-content/" /> - <LinkCard title="Bileşenler" href="/tr/guides/components/" /> -</CardGrid> -``` - -Yukarıdaki kod, sayfa üzerinde aşağıdaki gibi çıktı oluşturur. - -import { LinkCard } from '@astrojs/starlight/components'; - -<LinkCard - title="Starlight'ı Özelleştirmek" - description="Starlight sitenizi kendi özel stiliniz, yazı karakteriniz ve daha fazlası ile nasıl oluşturacağınızı öğrenin." - href="/tr/guides/customization/" -/> - -<CardGrid> - <LinkCard title="Markdown Oluşturmak" href="/tr/guides/authoring-content/" /> - <LinkCard title="Bileşenler" href="/tr/guides/components/" /> -</CardGrid> - -### Ara bölümler - -Ara bölümler (ayrıca "uyarı" ve "açıklama balonu" olarak da bilinir), sayfanın ana içeriği ile birlikte ikincil bilgi göstermek için kullanışlıdır. - -`<Aside>` bileşeni zorunlu olmayan `note` (varsayılan), `tip`, `caution` ya da `danger` değerini alan `type` niteliğine sahiptir. `title` niteliği eklemek varsayılan ara bölüm başlığını değiştirir. - -````mdx -# src/content/docs/example.mdx - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>Özel başlığı olmayan bir varsayılan ara bölüm</Aside> - -<Aside type="caution" title="Dikkat Et!"> - Özel bir başlık *ile* uyarı ara bölümü. -</Aside> - -<Aside type="tip"> - -Diğer içerikler de ara bölümde desteklenir. - -```js -// Örneğin bir kod parçacığı. -``` - -</Aside> - -<Aside type="danger">Şifreni kimseye verme.</Aside> -```` - -Yukarıdaki kod, sayfa üzerinde aşağıdaki gibi çıktı oluşturur: - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>Özel başlığı olmayan bir varsayılan ara bölüm</Aside> - -<Aside type="caution" title="Dikkat Et!"> - Özel bir başlık *ile* uyarı ara bölümü. -</Aside> - -<Aside type="tip"> - -Diğer içerikler de ara bölümde desteklenir. - -```js -// Örneğin bir kod parçacığı. -``` - -</Aside> - -<Aside type="danger">Şifreni kimseye verme.</Aside> - -Starlight, ayrıca `<Aside>` bileşenine alternatif olarak Markdown ve MDX içerisinde ara bölüm oluşturmak için özel bir sözdizimi sağlar. -[“Markdown'da İçerik Yazmak”](/tr/guides/authoring-content/#ara-bölümler) rehberine özel sözdizimi detayları için bakın. - -### Kod - -`<Code>` bileşenini [Markdown kod bloğu](/tr/guides/authoring-content/#kod-blokları) kullanmanın mümkün olmadığı zaman sözdizim vurgulu kod oluşturmak için kullanın - örneğin dosyalar, veritabanları ve API'ler gibi harici kaynaklardan gelen verileri oluşturmak için. - -`<Code>` bileşeninin destekleği niteliklerin tüm detaylarını [Expressive Code “Code Component” dokümanında](https://expressive-code.com/key-features/code-component/) inceleyin. - -```mdx -# src/content/docs/example.mdx - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('Bu bir dosya ya da İçerik Yönetim Sisteminden gelebilir!');`; -export const fileName = 'example.js'; -export const highlights = ['file', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> -``` - -Yukarıdaki kod, sayfa üzerinde aşağıdaki gibi çıktı oluşturur: - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('Bu bir dosya ya da İçerik Yönetim Sisteminden gelebilir!');`; -export const fileName = 'example.js'; -export const highlights = ['file', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> - -#### Alınan kod - -[Vite’nin `?raw` son ekini](https://vitejs.dev/guide/assets#importing-asset-as-string) herhangi kod dosyasını string olarak almak için kullanın. -`<Code>` bileşenine alınan bu string'i sayfanıza dahil etmek için ekleyin. - -```mdx title="src/content/docs/example.mdx" "?raw" -import { Code } from '@astrojs/starlight/components'; -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> -``` - -Yukarıdaki kod, sayfa üzerinde aşağıdaki gibi çıktı oluşturur: - -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> - -### Dosya Ağacı - -`<FileTree>` bileşenini dizin yapısını dosya ikonları ve toplanabilir alt dizinleri göstermek için kullanın. - -Dosyalarınızın yapısını ve dizinleri `<FileTree>` içerisinde [numaralandırılmamış Markdown listesi](https://www.markdownguide.org/basic-syntax/#unordered-lists) ile açıkça belirtin. -İç içe yerleşmiş liste kullanarak ya da belirli bir içeriksiz dizin oluşturmak için liste elemanının sonuna `/` ekleyerek alt dizin oluşturun. - -Aşağıdaki sözdizimi dosya ağacınının görünümünü özelleştirmek için kullanılabilir: - -- Dosya ya da dizinin ismini kalın yaparak vurgulayın. Örneğin `**README.md**`. -- Dosya ya da dizine isimden sonra metin ekleyerek yorum ekleyin. -- Dosyalara ya da dizinlere isim olarak `...` ya da `…` yazımını kullanarak ayrılmış bilgi alanı ekleyin. - -```mdx -# src/content/docs/example.mdx - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs **önemli** bir dosya -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> -``` - -Yukarıdaki kod, sayfa üzerinde aşağıdaki gibi çıktı oluşturur: - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs **önemli** bir dosya -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> - -### Adımlar - -`<Steps>` bileşenini numaralanmış görevler listesini biçimlendirmek için kullanın. -Her aşamasının açıkça belirtilmeye ihtiyaç duyan çok karmaşık adım adım rehberleri oluşturmak için kullanışlıdır. - -Standart Markdown sıralanmış listesini `<Steps>` bileşeni ile sarmalayın. -`<Steps>` bileşeni içerisinde tüm olağan Markdown sözdizimi uygulanabilir. - -````mdx title="src/content/docs/example.mdx" -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Bileşeni MDX dosyasına dahil edin: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Sıralanmış liste elemanlarını `<Steps>` ile sarmalayın. - -</Steps> -```` - -Yukarıdaki kod, sayfa üzerinde aşağıdaki gibi çıktı oluşturur: - -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. Bileşeni MDX dosyasına dahil edin: - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. Sıralanmış liste elemanlarını `<Steps>` ile sarmalayın. - -</Steps> - -### İkon - -import { Icon } from '@astrojs/starlight/components'; -import IconsList from '~/components/icons-list.astro'; - -Starlight, içeriğinizde görünmesi için `<Icon>` bileşenini kullanarak bir grup ortak ikonları kullanımınıza sunar. - -Her `<Icon>` [`name`](#tüm-i̇konlar) değerine ihtiyaç duyar ve isteğe bağlı olarak `label` eklenebilir. -`size` ve `color` nitelikleri ikonun görünümünü CSS birimleri ve renk değerleri ile ayarlamak için kullanılabilir. - -```mdx -# src/content/docs/example.mdx - -import { Icon } from '@astrojs/starlight/components'; - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> -``` - -Yukarıdaki kod, aşağıdaki gibi çıktı oluşturur: - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> - -#### Tüm İkonlar - -Mevcut tüm ikonların listesi aşağıdaki gibi ilişkili isimleriyle gösterilmiştir. Bileşen kodunu kopyalamak için bir ikona tıklayın. - -<IconsList /> diff --git a/docs/src/content/docs/uk/getting-started.mdx b/docs/src/content/docs/uk/getting-started.mdx index 18ff69cf..bc4ff462 100644 --- a/docs/src/content/docs/uk/getting-started.mdx +++ b/docs/src/content/docs/uk/getting-started.mdx @@ -125,7 +125,7 @@ description: Це сторінка на моїм сайті, що він пра - **Конфіґурація:** Дізнайтеся про поширені параметри в ґайді [“Налаштовування Starlight”](/uk/guides/customization/). - **Навіґація:** Спорудить бічну панель у розділі [“Навіґація бічною панеллю”](/uk/guides/sidebar/). -- **Компоненти:** Відкрийте вбудовані картки, вкладки та багато іншого в [“Компонентах”](/uk/guides/components/). +- **Компоненти:** Відкрийте вбудовані картки, вкладки та багато іншого в [“Компонентах”](/uk/components/using-components/). - **Розгортування:** Опублікуйте власну працю за допомогою посібника [“Розгорніть свій сайт”](https://docs.astro.build/guides/deploy/) в документації Astro. ## Оновлення Starlight diff --git a/docs/src/content/docs/zh-cn/getting-started.mdx b/docs/src/content/docs/zh-cn/getting-started.mdx index 58b7d9fb..fc2bd133 100644 --- a/docs/src/content/docs/zh-cn/getting-started.mdx +++ b/docs/src/content/docs/zh-cn/getting-started.mdx @@ -91,7 +91,7 @@ Starlight 已经准备好让你添加新内容或导入你现有的文件！ - **配置：** 在[自定义 Starlight](/zh-cn/guides/customization/)中了解常见选项。 - **导航：** 使用[侧边栏导航](/zh-cn/guides/sidebar/)指南设置你的侧边栏。 -- **组件：** 在[组件](/zh-cn/guides/components/)指南中发现内置的卡片、标签页等更多内容。 +- **组件：** 在[组件](/zh-cn/components/using-components/)指南中发现内置的卡片、标签页等更多内容。 - **部署：** 使用 Astro 文档中的[部署你的 Astro 站点](https://docs.astro.build/zh-cn/guides/deploy/)指南发布你的站点。 ## 更新 Starlight diff --git a/docs/src/content/docs/zh-cn/guides/components.mdx b/docs/src/content/docs/zh-cn/guides/components.mdx deleted file mode 100644 index f998a043..00000000 --- a/docs/src/content/docs/zh-cn/guides/components.mdx +++ /dev/null @@ -1,500 +0,0 @@ ---- -title: 组件 -description: 使用 Starlight 在 MDX 中使用组件 ---- - -组件让你可以轻松地重用 UI 或样式。 -例如，链接卡片或 YouTube 嵌入。 -Starlight 支持在 [MDX](https://mdxjs.com/) 文件中使用组件，并提供了一些常用组件供你使用。 - -[在 Astro 文档中了解更多关于构建组件的内容](https://docs.astro.build/zh-cn/core-concepts/astro-components/)。 - -## 使用组件 - -你可以通过在 MDX 文件中导入组件，然后像渲染 JSX 标签一样来使用组件。 -这些看起来像 HTML 标签，但是以大写字母开头，与你的 `import` 语句中的名称匹配： - -```mdx ---- -# src/content/docs/example.mdx -title: 欢迎来到我的文档 ---- - -import SomeComponent from '~/components/SomeComponent.astro'; -import AnotherComponent from '~/components/AnotherComponent.astro'; - -<SomeComponent prop="something" /> - -<AnotherComponent>组件也可以包含**嵌套内容**。</AnotherComponent> -``` - -因为 Starlight 是由 Astro 提供支持的，所以你可以在 MDX 文件中添加对任何 [支持的 UI 框架（React、Preact、Svelte、Vue、Solid、Lit 和 Alpine）](https://docs.astro.build/zh-cn/core-concepts/framework-components/) 构建的组件的支持。 -在 Astro 文档中了解更多关于 [在 MDX 中使用组件](https://docs.astro.build/zh-cn/guides/markdown-content/#在-mdx-中使用组件) 的内容。 - -### 与 Starlight 样式的兼容 - -Starlight 为你的 Markdown 内容应用了默认样式，例如在元素之间添加边距。 - -如果这些样式与你的组件的外观冲突，请在组件上设置 `not-content` 类来禁用它们。 - -```astro 'class="not-content"' ---- -// src/components/Example.astro ---- - -<div class="not-content"> - <p>不受 Starlight 默认内容样式的影响。</p> -</div> -``` - -## 内置组件 - -Starlight 为常见的文档用例提供了一些内置组件。 -这些组件可以从 `@astrojs/starlight/components` 包中获取。 - -### 选项卡 - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -你可以使用 `<Tabs>` 和 `<TabItem>` 组件显示一个选项卡界面。 -每个 `<TabItem>` 必须有一个 `label` 来显示给用户。 -使用可选的`icon`属性在标签旁包含一个[Starlight内置图标](#所有图标)。 - -```mdx -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -<Tabs> - <TabItem label="恒星" icon="star"> - 天狼星、织女星、参宿四 - </TabItem> - <TabItem label="卫星" icon="moon"> - 木卫一、木卫二、木卫三 - </TabItem> -</Tabs> -``` - -以上代码在页面上生成了以下选项卡： - -<Tabs> - <TabItem label="恒星" icon="star"> - 天狼星、织女星、参宿四 - </TabItem> - <TabItem label="卫星" icon="moon"> - 木卫一、木卫二、木卫三 - </TabItem> -</Tabs> - -#### 同步选项卡 - -通过添加 `syncKey` 属性来保持多个选项卡组同步。 - -拥有相同的 `syncKey` 值的所有 `<Tabs>` 都将展示相同的活动标签。这使得你的读者只需选择一次（例如他们的操作系统或包管理器），就可以看到他们的选择在页面导航中保持不变。 - -若要同步相关的选项卡，请为每个 `<Tabs>` 组件添加相同的 `syncKey` 属性，并确保它们都使用相同的 `<TabItem>` 标签： - -```mdx 'syncKey="constellations"' -# src/content/docs/example.mdx - -import { Tabs, TabItem } from '@astrojs/starlight/components'; - -_一些星座:_ - -<Tabs syncKey="星座"> - <TabItem label="猎户座">Bellatrix, Rigel, Betelgeuse</TabItem> - <TabItem label="双子座">Pollux, Castor A, Castor B</TabItem> -</Tabs> - -_一些系外行星:_ - -<Tabs syncKey="星座"> - <TabItem label="猎户座">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="双子座">Pollux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> -``` - -以上代码在页面上生成了以下内容： - -_一些星座:_ - -<Tabs syncKey="星座"> - <TabItem label="猎户座">Bellatrix, Rigel, Betelgeuse</TabItem> - <TabItem label="双子座">Pollux, Castor A, Castor B</TabItem> -</Tabs> - -_一些系外行星:_ - -<Tabs syncKey="星座"> - <TabItem label="猎户座">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem> - <TabItem label="双子座">Pollux b, HAT-P-24b, HD 50554 b</TabItem> -</Tabs> - -### 卡片 - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -你可以使用 `<Card>` 组件在与 Starlight 样式匹配的盒子中显示内容。 -当有足够的空间时，可以使用 `<CardGrid>` 组件将多个卡片封装在一起，以便并排显示卡片。 - -`<Card>` 需要一个 `title`，并且可以选择包含一个 `icon` 属性，该属性设置为 [Starlight 内置图标](#所有图标) 之一的名称。 - -```mdx -# src/content/docs/example.mdx - -import { Card, CardGrid } from '@astrojs/starlight/components'; - -<Card title="看看这个">你想要突出显示的有趣内容。</Card> - -<CardGrid> - <Card title="恒星" icon="star"> - 天狼星、织女星、参宿四 - </Card> - <Card title="卫星" icon="moon"> - 木卫一、木卫二、木卫三 - </Card> -</CardGrid> -``` - -以上代码在页面上生成了以下内容： - -<Card title="看看这个">你想要突出显示的有趣内容。</Card> - -<CardGrid> - <Card title="恒星" icon="star"> - 天狼星、织女星、参宿四 - </Card> - <Card title="卫星" icon="moon"> - 木卫一、木卫二、木卫三 - </Card> -</CardGrid> - -:::tip[提示] -在主页上使用卡片网格来显示项目的关键特性。 -添加 `stagger` 属性来垂直移动第二列的卡片，并增加视觉效果： - -```astro -<CardGrid stagger> - <!-- 卡片组件 --> -</CardGrid> -``` - -::: - -### 链接卡片 - -使用 `<LinkCard>` 组件来突出显示链接到不同页面的内容。 - -`<LinkCard>` 需要一个 `title` 和一个 [`href`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/a#href) 属性。你可以选择包含一个简短的 `description` 或其他链接属性，例如 `target`。 - -当有足够的空间时，将多个 `<LinkCard>` 组件组合在 `<CardGrid>` 中，以便并排显示卡片。 - -```mdx -# src/content/docs/example.mdx - -import { LinkCard, CardGrid } from '@astrojs/starlight/components'; - -<LinkCard - title="自定义 Starlight" - description="了解如何使用自定义样式、字体等打造你自己的 Starlight 网站。" - href="/zh-cn/guides/customization/" -/> - -<CardGrid> - <LinkCard title="创作 Markdown" href="/zh-cn/guides/authoring-content/" /> - <LinkCard title="组件" href="/zh-cn/guides/components/" /> -</CardGrid> -``` - -以上代码在页面上生成了以下内容： - -import { LinkCard } from '@astrojs/starlight/components'; - -<LinkCard - title="自定义 Starlight" - description="了解如何使用自定义样式、字体等打造你自己的 Starlight 网站。" - href="/zh-cn/guides/customization/" -/> - -<CardGrid> - <LinkCard title="创作 Markdown" href="/zh-cn/guides/authoring-content/" /> - <LinkCard title="组件" href="/zh-cn/guides/components/" /> -</CardGrid> - -### 链接按钮 - -使用 `<LinkButton>` 组件来创建视觉上独特的的操作链接。链接按钮对于引导用户到最相关或可操作的内容非常有用，通常用于落地页。 - -`<LinkButton>` 需要一个 [`href`](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/a#href) 属性，并且可选的接受其他链接属性，例如 `target`。 - -`icon` 属性可以选择性地设置为 [Starlight 内置图标之一的名称](#所有图标)，以在文本旁边包含一个图标。 -`iconPlacement` 属性可以通过将其设置为 `start`（默认为 `end`）来将图标放在文本之前。 - -使用 `variant` 属性自定义链接按钮的外观，可以设置为 `primary`（默认值）、`secondary` 或 `minimal`。 - -```mdx -# src/content/docs/example.mdx - -import { LinkButton } from '@astrojs/starlight/components'; - -<LinkButton href="/zh-cn/getting-started/">开始使用</LinkButton> -<LinkButton href="https://docs.astro.build" variant="secondary" icon="external"> - 相关内容：Astro -</LinkButton> -``` - -以上代码在页面上生成了以下内容： - -import { LinkButton } from '@astrojs/starlight/components'; - -<LinkButton href="/zh-cn/getting-started/">开始使用</LinkButton> -<LinkButton href="https://docs.astro.build" variant="secondary" icon="external"> - 相关内容：Astro -</LinkButton> - -### 旁白 - -旁白（也称为“警告”或“提醒”）对于在页面的主要内容旁边显示次要信息非常有用。 - -`<Aside>` 可以有一个可选的 `type` 属性，可以是 `note`（默认值）、`tip`、`caution` 或 `danger`。设置 `title` 属性会覆盖默认的旁白标题。 - -````mdx -# src/content/docs/example.mdx - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>没有自定义标题的默认旁白</Aside> - -<Aside type="caution" title="当心！"> - *带有* 自定义标题的警告旁白。 -</Aside> - -<Aside type="tip"> - -旁白中也支持其他内容。 - -```js -// 比如代码片段。 -``` - -</Aside> - -<Aside type="danger">不要把你的密码告诉任何人。</Aside> -```` - -以上代码在页面上生成了以下内容： - -import { Aside } from '@astrojs/starlight/components'; - -<Aside>没有自定义标题的默认旁白</Aside> - -<Aside type="caution" title="当心！"> - *带有* 自定义标题的警告旁白。 -</Aside> - -<Aside type="tip"> - -旁白中也支持其他内容。 - -```js -// 比如代码片段。 -``` - -</Aside> - -<Aside type="danger">不要把你的密码告诉任何人。</Aside> - -Starlight 还提供了一种在 Markdown 和 MDX 中渲染旁白的自定义语法，作为 `<Aside>` 组件的替代方案。 -有关自定义语法的详细信息，请参阅 [“在 Markdown 中创作内容”](/zh-cn/guides/authoring-content/#旁白) 指南。 - -### 代码块 - -当使用 [Markdown 代码块](/zh-cn/guides/authoring-content/#代码块) 行不通时，可以使用 `<Code>` 组件来渲染语法高亮的代码。例如，渲染来自文件、数据库或 API 等外部来源的数据。 - -有关 `<Code>` 支持的完整属性的详细信息，请参阅 [Expressive Code 的 “Code Component” 文档](https://expressive-code.com/key-features/code-component/)。 - -```mdx -# src/content/docs/example.mdx - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('这可能来自一个文件或CMS!');`; -export const fileName = 'example.js'; -export const highlights = ['文件', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> -``` - -以上代码在页面上生成了以下内容： - -import { Code } from '@astrojs/starlight/components'; - -export const exampleCode = `console.log('这可能来自一个文件或CMS!');`; -export const fileName = 'example.js'; -export const highlights = ['文件', 'CMS']; - -<Code code={exampleCode} lang="js" title={fileName} mark={highlights} /> - -#### 导入代码字符串 - -使用 [Vite 的 `?raw` 导入后缀](https://cn.vitejs.dev/guide/assets#importing-asset-as-string) 来将任何代码文件导入为字符串。 -然后，你可以将此导入的字符串传递给 `<Code>` 组件，以便将其包含在页面上。 - -```mdx title="src/content/docs/example.mdx" "?raw" -import { Code } from '@astrojs/starlight/components'; -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> -``` - -以上代码在页面上生成了以下内容： - -import importedCode from '/src/env.d.ts?raw'; - -<Code code={importedCode} lang="ts" title="src/env.d.ts" /> - -### 文件树 - -使用`<FileTree>`组件来显示带有文件图标和可折叠子目录的目录结构。 - -使用 `<FileTree>` 组件内置的 [Markdown 无序列表语法](https://www.markdownguide.org/basic-syntax/#unordered-lists)指定文件和目录的组织结构。使用嵌套的列表项创建子目录；若希望某个目录不显示具体内容，只需在列表项末尾添加斜杠`/`即可。 - -以下语法可用于自定义文件树的外观： - -- 通过加粗文件名或目录名来突出显示，例如 `**README.md**` -- 通过在名称后添加更多文本来为文件或目录添加注释 -- 使用 `...` 或 `…` 作为名称来添加占位符文件和目录。 - -```mdx -# src/content/docs/example.mdx - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs 一个 **重要** 的文件 -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> -``` - -以上代码在页面上生成了以下内容： - -import { FileTree } from '@astrojs/starlight/components'; - -<FileTree> - -- astro.config.mjs 一个 **重要** 的文件 -- package.json -- README.md -- src - - components - - **Header.astro** - - … -- pages/ - -</FileTree> - -### 步骤 - -使用 `<Steps>` 组件为任务的编号列表设置样式。这对于需要清晰突出地显示每个步骤的分布指南很有用。 - -将 `<Steps>` 包裹在标准 Markdown 有序列表中。通常所有 Markdown 语法都适用于 `<Steps>` 内部。 - -````mdx title="src/content/docs/example.mdx" -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. 在 MDX 文件中导入该组件 - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. 将有序列表放入该组件中 - -</Steps> -```` - -以上代码在页面上生成了以下内容： - -import { Steps } from '@astrojs/starlight/components'; - -<Steps> - -1. 在 MDX 文件中导入该组件 - - ```js - import { Steps } from '@astrojs/starlight/components'; - ``` - -2. 将有序列表放入该组件中 - -</Steps> - -### 徽章 - -import { Badge } from '@astrojs/starlight/components'; - -使用 `<Badge>` 组件来显示小块信息，如状态或标签。 - -将你想显示的内容传递给 `<Badge>` 组件的 `text` 属性。 - -默认情况下，徽章将使用你网站的主题突出色。要使用内置的徽章颜色，请将 `variant` 属性设置为以下值之一：`note`（蓝色）、`tip`（紫色）、`danger`（红色）、`caution`（橙色）或 `success`（绿色）。 - -`size` 属性（默认为 `small`）控制徽章文本的大小。`medium` 和 `large` 也是显示更大徽章的可用选项。 - -为了进一步自定义，可以使用其他 `<span>` 属性，如 `class` 或 `style`，并配合自定义 CSS。 - -```mdx title="src/content/docs/example.mdx" -import { Badge } from '@astrojs/starlight/components'; - -<Badge text="New" variant="tip" size="small" /> -<Badge text="Deprecated" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Custom" variant="success" style={{ fontStyle: 'italic' }} /> -``` - -以上代码在页面上生成了以下内容： - -<Badge text="New" variant="tip" size="small" /> -<Badge text="Deprecated" variant="caution" size="medium" /> -<Badge text="Starlight" variant="note" size="large" /> -<Badge text="Custom" variant="success" style={{ fontStyle: 'italic' }} /> - -### 图标 - -import { Icon } from '@astrojs/starlight/components'; -import IconsList from '~/components/icons-list.astro'; - -Starlight 提供了一组常用的图标，你可以使用 `<Icon>` 组件在你的内容中显示。 - -每个 `<Icon>` 都需要一个 [`name`](#所有图标)，并且可以选择性地包含一个 `label` 来为屏幕阅读器提供上下文。 -`size` 和 `color` 属性可以使用 CSS 单位和颜色值来调整图标的外观。 - -```mdx -# src/content/docs/example.mdx - -import { Icon } from '@astrojs/starlight/components'; - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> -``` - -以上代码在页面上生成了以下内容： - -<Icon name="star" color="goldenrod" size="2rem" /> -<Icon name="rocket" color="var(--sl-color-text-accent)" /> - -#### 所有图标 - -下面显示了所有可用图标的列表及其关联的名称。点击图标以复制其组件代码。 - -<IconsList /> diff --git a/docs/src/content/i18n/en.json b/docs/src/content/i18n/en.json new file mode 100644 index 00000000..e856b05d --- /dev/null +++ b/docs/src/content/i18n/en.json @@ -0,0 +1,3 @@ +{ + "component.preview": "Preview" +} diff --git a/docs/src/content/i18n/fr.json b/docs/src/content/i18n/fr.json new file mode 100644 index 00000000..c46cd41d --- /dev/null +++ b/docs/src/content/i18n/fr.json @@ -0,0 +1,3 @@ +{ + "component.preview": "Aperçu" +} diff --git a/packages/starlight/__tests__/basics/format-path.test.ts b/packages/starlight/__tests__/basics/format-path.test.ts index ce2fa110..8a1736a0 100644 --- a/packages/starlight/__tests__/basics/format-path.test.ts +++ b/packages/starlight/__tests__/basics/format-path.test.ts @@ -15,9 +15,9 @@ describe.each<{ options: FormatPathOptions; tests: Array<{ path: string; expecte // without trailing slash { path: '/api/v1/users', expected: '/api/v1/users.html' }, // with file extension - { path: '/guides/components.html', expected: '/guides/components.html' }, + { path: '/guides/project-structure.html', expected: '/guides/project-structure.html' }, // with file extension and trailing slash - { path: '/guides/components.html/', expected: '/guides/components.html' }, + { path: '/guides/project-structure.html/', expected: '/guides/project-structure.html' }, ], }, { @@ -30,9 +30,9 @@ describe.each<{ options: FormatPathOptions; tests: Array<{ path: string; expecte // without trailing slash { path: '/api/v1/users', expected: '/api/v1/users.html' }, // with file extension - { path: '/guides/components.html', expected: '/guides/components.html' }, + { path: '/guides/project-structure.html', expected: '/guides/project-structure.html' }, // with file extension and trailing slash - { path: '/guides/components.html/', expected: '/guides/components.html' }, + { path: '/guides/project-structure.html/', expected: '/guides/project-structure.html' }, ], }, { @@ -45,9 +45,9 @@ describe.each<{ options: FormatPathOptions; tests: Array<{ path: string; expecte // without trailing slash { path: '/api/v1/users', expected: '/api/v1/users.html' }, // with file extension - { path: '/guides/components.html', expected: '/guides/components.html' }, + { path: '/guides/project-structure.html', expected: '/guides/project-structure.html' }, // with file extension and trailing slash - { path: '/guides/components.html/', expected: '/guides/components.html' }, + { path: '/guides/project-structure.html/', expected: '/guides/project-structure.html' }, ], }, { @@ -60,9 +60,9 @@ describe.each<{ options: FormatPathOptions; tests: Array<{ path: string; expecte // without trailing slash { path: '/api/v1/users', expected: '/api/v1/users/' }, // with file extension - { path: '/guides/components.html', expected: '/guides/components/' }, + { path: '/guides/project-structure.html', expected: '/guides/project-structure/' }, // with file extension and trailing slash - { path: '/guides/components.html/', expected: '/guides/components/' }, + { path: '/guides/project-structure.html/', expected: '/guides/project-structure/' }, ], }, { @@ -75,9 +75,9 @@ describe.each<{ options: FormatPathOptions; tests: Array<{ path: string; expecte // without trailing slash { path: '/api/v1/users', expected: '/api/v1/users' }, // with file extension - { path: '/guides/components.html', expected: '/guides/components' }, + { path: '/guides/project-structure.html', expected: '/guides/project-structure' }, // with file extension and trailing slash - { path: '/guides/components.html/', expected: '/guides/components' }, + { path: '/guides/project-structure.html/', expected: '/guides/project-structure' }, ], }, { @@ -90,9 +90,9 @@ describe.each<{ options: FormatPathOptions; tests: Array<{ path: string; expecte // without trailing slash { path: '/api/v1/users', expected: '/api/v1/users' }, // with file extension - { path: '/guides/components.html', expected: '/guides/components' }, + { path: '/guides/project-structure.html', expected: '/guides/project-structure' }, // with file extension and trailing slash - { path: '/guides/components.html/', expected: '/guides/components' }, + { path: '/guides/project-structure.html/', expected: '/guides/project-structure' }, ], }, ])( diff --git a/packages/starlight/__tests__/basics/navigation-labels.test.ts b/packages/starlight/__tests__/basics/navigation-labels.test.ts index 5e070d83..7784c04b 100644 --- a/packages/starlight/__tests__/basics/navigation-labels.test.ts +++ b/packages/starlight/__tests__/basics/navigation-labels.test.ts @@ -10,7 +10,10 @@ vi.mock('astro:content', async () => { title: 'Eco-friendly docs', sidebar: { label: 'Environmental impact' } }, ], ['guides/authoring-content.mdx', { title: 'Authoring Markdown' }], - ['guides/components.mdx', { title: 'Using components', sidebar: { label: 'Components' } }], + [ + 'guides/project-structure.mdx', + { title: 'Project Structure', sidebar: { label: 'Structure' } }, + ], ], }) ); @@ -50,9 +53,9 @@ describe('getSidebar', () => { { "attrs": {}, "badge": undefined, - "href": "/guides/components/", + "href": "/guides/project-structure/", "isCurrent": false, - "label": "Components", + "label": "Structure", "type": "link", }, ], diff --git a/packages/starlight/__tests__/basics/navigation-order.test.ts b/packages/starlight/__tests__/basics/navigation-order.test.ts index 39850e03..f1935e7c 100644 --- a/packages/starlight/__tests__/basics/navigation-order.test.ts +++ b/packages/starlight/__tests__/basics/navigation-order.test.ts @@ -7,7 +7,7 @@ vi.mock('astro:content', async () => ['index.mdx', { title: 'Home Page' }], ['environmental-impact.md', { title: 'Eco-friendly docs', sidebar: { order: 1 } }], ['guides/authoring-content.mdx', { title: 'Authoring Markdown' }], - ['guides/components.mdx', { title: 'Components', sidebar: { order: 0 } }], + ['guides/project-structure.mdx', { title: 'Project Structure', sidebar: { order: 0 } }], ], }) ); @@ -23,9 +23,9 @@ describe('getSidebar', () => { { "attrs": {}, "badge": undefined, - "href": "/guides/components/", + "href": "/guides/project-structure/", "isCurrent": false, - "label": "Components", + "label": "Project Structure", "type": "link", }, { diff --git a/packages/starlight/__tests__/basics/navigation.test.ts b/packages/starlight/__tests__/basics/navigation.test.ts index fb4d5110..50496b4e 100644 --- a/packages/starlight/__tests__/basics/navigation.test.ts +++ b/packages/starlight/__tests__/basics/navigation.test.ts @@ -8,7 +8,7 @@ vi.mock('astro:content', async () => ['environmental-impact.md', { title: 'Eco-friendly docs' }], ['guides/authoring-content.mdx', { title: 'Authoring Markdown' }], ['reference/frontmatter.md', { title: 'Frontmatter Reference', sidebar: { hidden: true } }], - ['guides/components.mdx', { title: 'Components' }], + ['guides/project-structure.mdx', { title: 'Project Structure' }], ], }) ); @@ -48,9 +48,9 @@ describe('getSidebar', () => { { "attrs": {}, "badge": undefined, - "href": "/guides/components/", + "href": "/guides/project-structure/", "isCurrent": false, - "label": "Components", + "label": "Project Structure", "type": "link", }, ], @@ -145,9 +145,9 @@ describe('flattenSidebar', () => { { "attrs": {}, "badge": undefined, - "href": "/guides/components/", + "href": "/guides/project-structure/", "isCurrent": false, - "label": "Components", + "label": "Project Structure", "type": "link", }, ] @@ -194,7 +194,7 @@ describe('getPrevNextLinks', () => { }); test('returns no next link for last item', () => { - const sidebar = getSidebar('/guides/components/', undefined); + const sidebar = getSidebar('/guides/project-structure/', undefined); const links = getPrevNextLinks(sidebar, true, {}); expect(links.next).toBeUndefined(); }); diff --git a/packages/starlight/__tests__/basics/pagination-with-base.test.ts b/packages/starlight/__tests__/basics/pagination-with-base.test.ts index 031964dd..fa85f910 100644 --- a/packages/starlight/__tests__/basics/pagination-with-base.test.ts +++ b/packages/starlight/__tests__/basics/pagination-with-base.test.ts @@ -10,7 +10,7 @@ vi.mock('astro:content', async () => ['index.mdx', { title: 'Home Page' }], ['environmental-impact.md', { title: 'Eco-friendly docs' }], ['guides/authoring-content.mdx', { title: 'Authoring Markdown' }], - ['guides/components.mdx', { title: 'Components' }], + ['guides/project-structure.mdx', { title: 'Project Structure' }], ['reference/frontmatter.md', { title: 'Frontmatter Reference' }], ], }) @@ -28,7 +28,7 @@ describe('without base', async () => { test('pagination links are inferred correctly with no frontmatter', () => { const links = getPrevNextLinks(sidebar, true, {}); - expect(links.prev?.href).toBe('/guides/components/'); + expect(links.prev?.href).toBe('/guides/project-structure/'); expect(links.next?.href).toBeUndefined(); }); @@ -63,7 +63,7 @@ describe('with base', () => { test('pagination links are inferred correctly with no frontmatter', () => { const links = getPrevNextLinks(sidebar, true, {}); - expect(links.prev?.href).toBe('/test-base/guides/components/'); + expect(links.prev?.href).toBe('/test-base/guides/project-structure/'); expect(links.next?.href).toBeUndefined(); }); diff --git a/packages/starlight/__tests__/basics/starlight-page-route-data.test.ts b/packages/starlight/__tests__/basics/starlight-page-route-data.test.ts index c3510a65..abba3a76 100644 --- a/packages/starlight/__tests__/basics/starlight-page-route-data.test.ts +++ b/packages/starlight/__tests__/basics/starlight-page-route-data.test.ts @@ -16,7 +16,7 @@ vi.mock('astro:content', async () => ['index.mdx', { title: 'Home Page' }], ['getting-started.mdx', { title: 'Getting Started' }], ['guides/authoring-content.mdx', { title: 'Authoring Markdown' }], - ['guides/components.mdx', { title: 'Components' }], + ['guides/project-structure.mdx', { title: 'Project Structure' }], ['reference/frontmatter.md', { title: 'Frontmatter Reference' }], ], }) @@ -138,9 +138,9 @@ test('uses generated sidebar when no sidebar is provided', async () => { { "attrs": {}, "badge": undefined, - "href": "/guides/components/", + "href": "/guides/project-structure/", "isCurrent": false, - "label": "Components", + "label": "Project Structure", "type": "link", }, ], @@ -226,9 +226,9 @@ test('uses provided sidebar if any', async () => { { "attrs": {}, "badge": undefined, - "href": "/guides/components/", + "href": "/guides/project-structure/", "isCurrent": false, - "label": "Components", + "label": "Project Structure", "type": "link", }, ], diff --git a/packages/starlight/__tests__/build-format-file/navigation.test.ts b/packages/starlight/__tests__/build-format-file/navigation.test.ts index f91e98a3..30d3d105 100644 --- a/packages/starlight/__tests__/build-format-file/navigation.test.ts +++ b/packages/starlight/__tests__/build-format-file/navigation.test.ts @@ -10,7 +10,7 @@ vi.mock('astro:content', async () => ['reference/frontmatter.md', { title: 'Frontmatter Reference' }], // @ts-expect-error — Using a slug not present in Starlight docs site ['api/v1/users.md', { title: 'Users API' }], - ['guides/components.mdx', { title: 'Components' }], + ['guides/project-structure.mdx', { title: 'Project Structure' }], ], }) ); diff --git a/packages/starlight/__tests__/remark-rehype/rehype-file-tree.test.ts b/packages/starlight/__tests__/remark-rehype/rehype-file-tree.test.ts index fb6acd42..dcbe62f5 100644 --- a/packages/starlight/__tests__/remark-rehype/rehype-file-tree.test.ts +++ b/packages/starlight/__tests__/remark-rehype/rehype-file-tree.test.ts @@ -9,7 +9,7 @@ describe('validation', () => { "[AstroUserError]: The \`<FileTree>\` component expects its content to be a single unordered list but found no child elements. Hint: - To learn more about the \`<FileTree>\` component, see https://starlight.astro.build/guides/components/#file-tree" + To learn more about the \`<FileTree>\` component, see https://starlight.astro.build/components/file-tree/" ` ); }); @@ -22,7 +22,7 @@ describe('validation', () => { "[AstroUserError]: The \`<FileTree>\` component expects its content to be a single unordered list but found multiple child elements: \`<p>\` - \`<ul>\`. Hint: - To learn more about the \`<FileTree>\` component, see https://starlight.astro.build/guides/components/#file-tree" + To learn more about the \`<FileTree>\` component, see https://starlight.astro.build/components/file-tree/" ` ); }); @@ -33,7 +33,7 @@ describe('validation', () => { "[AstroUserError]: The \`<FileTree>\` component expects its content to be an unordered list but found the following element: \`<ol>\`. Hint: - To learn more about the \`<FileTree>\` component, see https://starlight.astro.build/guides/components/#file-tree" + To learn more about the \`<FileTree>\` component, see https://starlight.astro.build/components/file-tree/" ` ); }); @@ -44,7 +44,7 @@ describe('validation', () => { "[AstroUserError]: The \`<FileTree>\` component expects its content to be an unordered list with at least one list item. Hint: - To learn more about the \`<FileTree>\` component, see https://starlight.astro.build/guides/components/#file-tree" + To learn more about the \`<FileTree>\` component, see https://starlight.astro.build/components/file-tree/" ` ); }); diff --git a/packages/starlight/__tests__/remark-rehype/rehype-steps.test.ts b/packages/starlight/__tests__/remark-rehype/rehype-steps.test.ts index a7081023..de79b4cd 100644 --- a/packages/starlight/__tests__/remark-rehype/rehype-steps.test.ts +++ b/packages/starlight/__tests__/remark-rehype/rehype-steps.test.ts @@ -7,7 +7,7 @@ test('empty component throws an error', () => { "[AstroUserError]: The \`<Steps>\` component expects its content to be a single ordered list (\`<ol>\`) but found no child elements. Hint: - To learn more about the \`<Steps>\` component, see https://starlight.astro.build/guides/components/#steps" + To learn more about the \`<Steps>\` component, see https://starlight.astro.build/components/steps/" ` ); }); @@ -18,7 +18,7 @@ test('component with non-element content throws an error', () => { "[AstroUserError]: The \`<Steps>\` component expects its content to be a single ordered list (\`<ol>\`) but found no child elements. Hint: - To learn more about the \`<Steps>\` component, see https://starlight.astro.build/guides/components/#steps" + To learn more about the \`<Steps>\` component, see https://starlight.astro.build/components/steps/" ` ); }); @@ -29,7 +29,7 @@ test('component with non-`<ol>` content throws an error', () => { "[AstroUserError]: The \`<Steps>\` component expects its content to be a single ordered list (\`<ol>\`) but found the following element: \`<p>\`. Hint: - To learn more about the \`<Steps>\` component, see https://starlight.astro.build/guides/components/#steps + To learn more about the \`<Steps>\` component, see https://starlight.astro.build/components/steps/ Full HTML passed to \`<Steps>\`: @@ -47,7 +47,7 @@ test('component with multiple children throws an error', () => { "[AstroUserError]: The \`<Steps>\` component expects its content to be a single ordered list (\`<ol>\`) but found multiple child elements: \`<ol>\`, \`<p>\`, \`<ol>\`. Hint: - To learn more about the \`<Steps>\` component, see https://starlight.astro.build/guides/components/#steps + To learn more about the \`<Steps>\` component, see https://starlight.astro.build/components/steps/ Full HTML passed to \`<Steps>\`: diff --git a/packages/starlight/__tests__/sidebar/navigation-badges.test.ts b/packages/starlight/__tests__/sidebar/navigation-badges.test.ts index 4c81ac80..c54546ba 100644 --- a/packages/starlight/__tests__/sidebar/navigation-badges.test.ts +++ b/packages/starlight/__tests__/sidebar/navigation-badges.test.ts @@ -21,7 +21,7 @@ vi.mock('astro:content', async () => ['reference/frontmatter.md', { title: 'Frontmatter Reference', sidebar: { badge: 'New' } }], // @ts-expect-error — Using a slug not present in Starlight docs site ['api/v1/users.md', { title: 'Users API' }], - ['guides/components.mdx', { title: 'Components' }], + ['guides/project-structure.mdx', { title: 'Project Structure' }], ], }) ); diff --git a/packages/starlight/__tests__/sidebar/navigation-hidden.test.ts b/packages/starlight/__tests__/sidebar/navigation-hidden.test.ts index bbf7f9a5..631daae1 100644 --- a/packages/starlight/__tests__/sidebar/navigation-hidden.test.ts +++ b/packages/starlight/__tests__/sidebar/navigation-hidden.test.ts @@ -10,7 +10,7 @@ vi.mock('astro:content', async () => ['reference/frontmatter.md', { title: 'Frontmatter Reference', sidebar: { hidden: true } }], // @ts-expect-error — Using a slug not present in Starlight docs site ['api/v1/users.md', { title: 'Users API' }], - ['guides/components.mdx', { title: 'Components' }], + ['guides/project-structure.mdx', { title: 'Project Structure' }], ], }) ); diff --git a/packages/starlight/__tests__/sidebar/navigation-order.test.ts b/packages/starlight/__tests__/sidebar/navigation-order.test.ts index c90d4159..5b754f60 100644 --- a/packages/starlight/__tests__/sidebar/navigation-order.test.ts +++ b/packages/starlight/__tests__/sidebar/navigation-order.test.ts @@ -10,7 +10,7 @@ vi.mock('astro:content', async () => ['reference/frontmatter.md', { title: 'Frontmatter Reference', sidebar: { order: 1 } }], // @ts-expect-error — Using a slug not present in Starlight docs site ['api/v1/users.md', { title: 'Users API' }], - ['guides/components.mdx', { title: 'Components' }], + ['guides/project-structure.mdx', { title: 'Project Structure' }], ], }) ); diff --git a/packages/starlight/__tests__/sidebar/navigation-unicode.test.ts b/packages/starlight/__tests__/sidebar/navigation-unicode.test.ts index f66f8e25..f3026d4e 100644 --- a/packages/starlight/__tests__/sidebar/navigation-unicode.test.ts +++ b/packages/starlight/__tests__/sidebar/navigation-unicode.test.ts @@ -10,7 +10,7 @@ vi.mock('astro:content', async () => ['reference/frontmatter.md', { title: 'Frontmatter Reference' }], // @ts-expect-error — Using a slug not present in Starlight docs site ['api/v1/用户.md', { title: 'Path with non-ASCII characters' }], - ['guides/components.mdx', { title: 'Components' }], + ['guides/project-structure.mdx', { title: 'Project Structure' }], ], }) ); diff --git a/packages/starlight/__tests__/sidebar/navigation.test.ts b/packages/starlight/__tests__/sidebar/navigation.test.ts index 321f00fa..2ae254a5 100644 --- a/packages/starlight/__tests__/sidebar/navigation.test.ts +++ b/packages/starlight/__tests__/sidebar/navigation.test.ts @@ -12,7 +12,7 @@ vi.mock('astro:content', async () => ['reference/frontmatter/foo.mdx', { title: 'Foo' }], // @ts-expect-error — Using a slug not present in Starlight docs site ['api/v1/users.md', { title: 'Users API' }], - ['guides/components.mdx', { title: 'Components' }], + ['guides/project-structure.mdx', { title: 'Project Structure' }], ], }) ); diff --git a/packages/starlight/user-components/rehype-file-tree.ts b/packages/starlight/user-components/rehype-file-tree.ts index 2f96d5c5..1bdb1907 100644 --- a/packages/starlight/user-components/rehype-file-tree.ts +++ b/packages/starlight/user-components/rehype-file-tree.ts @@ -240,7 +240,7 @@ function isElementNode(node: ElementContent): node is Element { function throwFileTreeValidationError(message: string): never { throw new AstroError( message, - 'To learn more about the `<FileTree>` component, see https://starlight.astro.build/guides/components/#file-tree' + 'To learn more about the `<FileTree>` component, see https://starlight.astro.build/components/file-tree/' ); } diff --git a/packages/starlight/user-components/rehype-steps.ts b/packages/starlight/user-components/rehype-steps.ts index 184df00e..40ccf871 100644 --- a/packages/starlight/user-components/rehype-steps.ts +++ b/packages/starlight/user-components/rehype-steps.ts @@ -67,7 +67,7 @@ export const processSteps = (html: string | undefined) => { class StepsError extends AstroError { constructor(message: string, html?: string) { let hint = - 'To learn more about the `<Steps>` component, see https://starlight.astro.build/guides/components/#steps'; + 'To learn more about the `<Steps>` component, see https://starlight.astro.build/components/steps/'; if (html) { hint += '\n\nFull HTML passed to `<Steps>`:\n' + prettyPrintHtml(html); } |