Markdown Features
Docusaurus utilise GitHub Flavored Markdown (GFM). En savoir plus sur les champs spécifiques de Docusaurus lors de l'écriture de Markdown.
Entêtes de Markdown
Documents
Les documents utilisent les champs d'entête markdown suivants qui sont entourés par une ligne --- de chaque côté :
id: Un identifiant unique de document. Si ce champ n'est pas présent, le fichier id du document prendra par défaut son nom de fichier (sans l'extension).
title: Le titre de votre document. Si ce champ n'est pas présent, le title du document sera par défaut celui de son id.
hide_title : Si vous voulez cacher le titre en haut de la doc.
sidebar_label : Le texte affiché dans la barre latérale du document et dans le bouton suivant/précédent pour ce document. Si ce champ n'est pas présent, le sidebar_label du document sera par défaut celui de son title.
Par exemple :
---
id : doc1
titre : Mon Document
sidebar_label : Document
---
Les documents versionnés ont leurs identifiants modifiés pour inclure le numéro de version lorsqu'ils sont copiés. Le nouvel id est version-${version}-${id} où ${version} est le numéro de version de ce document et ${id} est l'original id. De plus, les documents versionnés obtiennent un champ original_id supplémentaire avec l'identifiant du document original.
Par exemple :
---
id: version-1.0.0-doc1
title: Mon Document
sidebar_label: Document
original_id: doc1
---
custom_edit_url: L'url pour éditer le document. Si ce champ n'est pas présent, l'url du document va retournera editUrl depuis les champs optionnel de siteConfig.js. Consulter les docs de siteConfig.js pour plus d'informations.
Par exemple :
---
id: doc-markdown
title: Fonctionnalités de Markdown
custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md
---
Publications de blog
Les articles du blog suivent les entêtes de markdown qui sont encadrées par une ligne --- de chaque coté:
titre: Le titre de cet article du blog.
author : L'auteur de cet article du blog. Si ce champ est omis, aucun nom d'auteur ne sera affiché.
authorURL : Une page vers laquelle se connecter lorsqu'un utilisateur du site clique sur le nom de l'auteur. Si ce champ est omis, le nom de l'auteur ne sera lié à rien.
authorFBID : L'identifiant Facebook de l'auteur, utilisé uniquement pour obtenir la photo de profil de l'auteur à afficher avec l'article du blog. Si ce champ est omis, aucune image d’auteur ne sera affichée pour l'article du blog.
Par exemple :
---
title: Mon premier post
author: Frank Li
authorURL: http://twitter.com/franchementli
authorFBID: 100002976521003
---
Fonctionnalités supplémentaires
Docusaurus prend en charge certaines fonctionnalités supplémentaires lors de l'écriture de la documentation en markdown.
Lier d'autres documents
Vous pouvez utiliser des url relatives à d'autre fichiers de documentation qui seront automatiquement convertit en des liés correspondant quand ils seront rendus.
Exemple :
[Ce lien vers un autre document](other-document.md)
Ce markdown sera automatiquement converti en un lien vers /docs/other-document.html (ou le lien correctement traduit/versionné) une fois qu'il sera affiché.
Ceci peut vous aider quand vous voudrez naviguer dans la documentation sur GitHub puisque les liens seront des liens fonctionnels vers d'autres document (toujours sur GitHub), mais les documents auront des liens HTML corrects lorsqu'ils seront rendus.
Lien vers les images et autres ressources
Des assets statiques peuvent être inclus de la même façon que le sont les documents, en utilisant des liens relatifs. Les ressources statiques utilisées dans les documents et les blogs doivent aller respectivement dans docs/assets et website/blog/assets. Le markdown sera converti avec des chemins de liens corrects afin que ces chemins fonctionnent pour les documents de toutes les langues et versions.
Exemple :
Génération d'une table des matières
Vous pouvez créer une liste auto-générée de liens, qui seront utiles pour une table des matières pour la documentation de l'API.
Dans votre fichier Markdown, insérez une ligne avec le texte ``. Écrivez votre documentation en utilisant les entêtes h3 pour chaque fonction à l'intérieur d'un bloc de code. Cela va être trouvé par Docusaurus et une liste de lien de toute les sections va être inséré à la place du texte <AUTOGENERATED_TABLE_OF_CONTENTS>.
Exemple :
### `docusaurus.function(a, b)`
Texte décrivant ma fonction
### `docdoc(file)`
Texte décrivant ma fonction
ceci donnera une table des matières des fonctions :
- `docusaurus.function(a, b)`
- `docdoc(file)`
et chaque fonction sera liée à leurs sections correspondantes dans la page.
Onglets de code spécifiques au langage
Affiche le code dans plusieurs langages de programmation en utilisant des onglets de code. Tout d'abord, marquez le début et la fin d'un groupe d'onglets de code, en utilisant respectivement <!-- DOCUSAURUS_CODE_TABS --> et <! - END_DOCUSAURUS_CODE_TABS --> dans votre markdown. Ensuite, démarrez chaque onglet avec <!--[TAB_TITLE]-->.
En ajoutant le code suivant à votre fichier Markdown :
cela produira :
console.log('Hello, world!');
print('Hello, world!')
#include <stdio.h>
int main() {
printf("Hello World!");
return 0;
}
program HelloWorld;
begin
WriteLn('Hello, world!');
end.
Coloration syntaxique
La coloration syntaxique est activée par défaut sur les blocs de code clôturés. Le langage devrait être détectée automatiquement, mais vous pouvez parfois obtenir de meilleurs résultats en spécifiant le langage. Vous pouvez le faire à l'aide d'un info string, en suivant les trois backticks d'ouverture. L'exemple JavaScript suivant...
```js
ReactDOM.render(<h1>Hello, world!</h1>, document.getElementById('root'));
```
...serait rendu avec la coloration syntaxique comme ceci :
ReactDOM.render(<h1>Hello, world!</h1>, document.getElementById('root'));
La mise en surbrillance est fournie par Highlight.js en utilisant le thème spécifié dans votre fichier siteConfig.js dans la partie de la clé highlight :
{
...
highlight: {
theme: 'default'
}
...
}
Vous pouvez trouver la liste complète des thèmes pris en charge dans le dossier styles deHighlight.js .
Ajout de langues supplémentaires
Bien que Highlight.js fournit le support pour de nombreux langages populaires, vous pouvez trouver le besoin d'enregistrer un support linguistique supplémentaire. Pour ces cas, nous fournissons une issue de secours en exposant la constante hljs dans la clé de configuration highlight. Cela vous permet d'appeler registerLanguage :
{
...
highlight: {
theme: 'default',
hljs: function(hljs) {
hljs.registerLanguage('galacticbasic', function(hljs) {
// ...
});
}
}
}
Utilisation de Prism comme coloration syntaxique supplémentaire
Vous pouvez également opter pour utiliser Prism de façon à surligner certains langages présent dans la liste ici. Indiquez ces langages dans le champ usePrism dans votre siteConfig.js
Exemple :
// siteConfig.js
usePrism: ['jsx']
Remarquez que le bloc de code au dessous utilise la syntaxe JSX formater avec Prism.
class Example extends React.Component {
render() {
return (
<View style={{flex: 1, alignItems: 'center', justifyContent: 'center'}}>
<Text>Docusaurus</Text>
<Button
title="Click me"
onPress={() => this.props.navigation.push('Docusaurus')}
/>
</View>
);
}
}
Ajout des boutons de copie de code
Docusaurus permet d'ajouter des boutons pour copier le code dans des blocs de code clôturés. Veuillez suivre les instructions ici pour ajouter les boutons "Copier" à vos blocs de code.