Markdown Features
Cabeceras de Markdown
Documentos
Los documentos usan los siguientes campos de cabecera encerrados por una línea de comando --- a cada lado:
id: A unique document id. If this field is not present, the document's id will default to its file name (without the extension).
title: The title of your document. If this field is not present, the document's title will default to its id.
hide_title: Whether to hide the title at the top of the doc.
sidebar_label: The text shown in the document sidebar for this document. If this field is not present, the document's sidebar_label will default to its title.
Por ejemplo:
id: doc1
title: Mi Documento
sidebar_label: Documento
Las distintas versiones del documento tienen sus ids alterados para incluir el número de la versión cuando son copiados. El nuevo id es version-${version}-${id}, donde ${version} es el número de la versión del documento y ${id} es el id original. Además, a las versiones del documento se les añade un campo original_id junto al id del documento original.
Por ejemplo:
d: version-1.0.0-doc1
title: Mi Documento
sidebar_label: Documento
original_id: doc1
custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.
Por ejemplo:
---
id: doc-markdown
title: Markdown Features
custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
---
Blog de publicaciones
Las publicaciones del blog usan los siguientes campos de cabecera encerrados por una línea --- a cada lado:
title: el título de la publicación del blog.
author: The author of this blog post. If this field is omitted, no author name will be shown.
authorURL: A page to link to when a site user clicks the author's name. If this field is omitted, the author's name will not link to anything.
authorFBID: el id de Facebook del autor. Se usa solamente para mostrar la foto de perfil del autor con la publicación del blog. Si se omite este campo, no aparecerá la foto del autor en la publicación del post.
Por ejemplo:
title: Mi primera publicación
author: Frank Li
authorURL: http://twitter.com/franchementli
authorFBID: 100002976521003
Características adicionales
Docusaurus es compatible con algunas características adicionales al escribir documentación en markdown.
Enlazar otros documentos
Se pueden utilizar urls relativos a otros archivos de documentación que se convertirán automáticamente a los enlaces html correspondientes cuando sean renderizados.
Ejemplo:
[Se enlaza con otro documento] (otro-documento.md)
Este markdown se convertirá automáticamente en un enlace /docs/other-document.html (o en un enlace adecuadamente traducido) cuando sea renderizado.
Esto puede ayudar cuando se quiere navegar a través de docs en GitHub, ya que los enlaces de allí serán enlaces operativos que llevarán al usuario a otros documentos (ubicados en GitHub). Los documentos tendrán los enlaces html correctos cuando sean renderizados.
Enlazar a imágenes y otros recursos
Los recursos estáticos pueden ser enlazados de la misma manera que los documentos, usando las urls relativas. Los recursos estáticos utilizados en los documentos y blogs deben ir dentro de docs/assets y website/blog/assets, respectivamente. El markdown será convertido en las rutas de enlace correspondientes, y así estas rutas funcionarán para los documentos de todos los idiomas y versiones.
Ejemplo:
Generar tabla de contenidos
Se puede hacer una lista que genere enlaces automáticamente, la cual puede ser útil como una tabla de contenidos para documentación API.
In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. Escriba su documentación utilizando las cabeceras h3 para cada función dentro de un bloque de código. These will be found by Docusaurus and a list of links to these sections will inserted at the text <AUTOGENERATED_TABLE_OF_CONTENTS>.
Ejemplo:
### `docusaurus.function(a, b)`
Text describing my function
### `docdoc(file)`
Text describing my function
dirigirá a la tabla de contenido de las funciones:
- `docusaurus.function(a, b)`
- `docdoc(file)`
y cada función se enlazará a su sección correspondiente en la página.
Syntax Highlighting
Syntax highlighting is enabled by default on fenced code blocks. The language should be detected automatically, but you can sometimes get better results by specifying the language. You can do so using an info string, following the three opening backticks. The following JavaScript example...
```js
ReactDOM.render(
<h1>Hello, world!</h1>,
document.getElementById('root')
);
```
...would be rendered with syntax highlighting like so:
ReactDOM.render(
<h1>Hello, world!</h1>,
document.getElementById('root')
);
Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:
{
...
highlight: {
theme: 'default'
}
...
}
You can find the full list of supported themes in the Highlight.js styles directory.
Registering additional languages
While Highlight.js provides support for many popular languages out of the box, you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the hljs constant as part of the highlight config key. This in turn allows you to call registerLanguage:
{
...
highlight: {
theme: 'default',
hljs: function(hljs) {
hljs.registerLanguage('galacticbasic', function(hljs) {
// ...
});
}
}
}