1. El proyecto MDN
  2. Pautas de redacción
  3. Estructuras de página
  4. Tipos de página
  5. Plantilla de página de inicio de API

Esta página ha sido traducida del inglés por la comunidad. Aprende más y únete a la comunidad de MDN Web Docs.

View in English Always switch to English

Plantilla de página de inicio de API

Nota: Elimina toda esta nota explicativa antes de publicar

Front matter de la página:

El front matter en la parte superior de la página se usa para definir los "metadatos de la página". Actualiza los valores según corresponda para la interfaz en particular.

md
---
title: NameOfTheAPI API
slug: Web/API/NameOfTheAPI_API
page-type: web-api-overview
status:
  - deprecated
  - experimental
  - non-standard
---
title

El título que se muestra en la parte superior de la página. Es el nombre de la API seguido del texto "API": NameOfTheAPI API. Por ejemplo, WebXR Device tiene el título WebXR Device API, y Fetch tiene el título Fetch API.

slug

El final de la ruta URL después de https://developer.mozilla.org/es/docs/). Tendrá un formato como Web/API/NameOfTheAPI_API. Por ejemplo, el slug de WebXR Device API es Web/API/WebXR_Device_API.

page-type

La clave page-type para las páginas de inicio Web/API siempre es web-api-overview.

status

Indicadores que describen el estado de esta característica. Es un array que puede contener uno o más de los siguientes valores: experimental, deprecated, non-standard. Esta clave no debe establecerse manualmente: se establece automáticamente en función de los valores de los datos de compatibilidad del navegador para dicha característica. Consulta "Cómo se añaden o actualizan los estados de las características".

Macros de la parte superior de la página

Varias llamadas a macros aparecen en la parte superior de la sección de contenido (justo debajo del front matter de la página).

La cadena de herramientas añade estas macros automáticamente (no es necesario añadirlas ni eliminarlas):

  • {{SeeCompatTable}}: genera un aviso de Esta es una tecnología experimental que indica que la tecnología es experimental. Si es experimental y la tecnología está oculta tras una preferencia (pref) en Firefox, también debes completar una entrada para ella en la página Funciones experimentales en Firefox.
  • {{Deprecated_Header}}: genera un aviso de Obsoleto que indica que se desaconseja el uso de la tecnología.
  • {{Non-standard_Header}}: genera un aviso de No estándar que indica que la característica no forma parte de ninguna especificación.

Actualiza o eliminar las siguientes macros según las indicaciones a continuación:

  • {{SecureContext_Header}}: genera un aviso de Contexto seguro que indica que la tecnología solo está disponible en un contexto seguro. Si no es así, puedes eliminar la llamada a la macro. Si es así, también debes completar una entrada para ella en la página Características restringidas a contextos seguros.
  • {{AvailableInWorkers}}: genera una nota de Disponible en workers que indica que la tecnología está disponible en un contexto de worker. Si solo está disponible en el contexto de ventana (window), puedes eliminar la llamada a la macro. Si también está disponible, o solo está disponible en el contexto de worker, es posible que también debas pasarle un parámetro debido a su disponibilidad (consulta el código fuente de la macro {{AvailableInWorkers}} para ver todos los valores disponibles); también es posible que debas completar una entrada para ella en la página Web API disponibles en workers.
  • {{APIRef("GroupDataName")}}: esto genera la barra lateral de referencia de la izquierda que muestra enlaces de referencia rápida relacionados con la página actual. Por ejemplo, todas las páginas de la WebVR API tienen la misma barra lateral, que apunta a las demás páginas de la API. Para generar la barra lateral correcta para tu API, debes añadir una entrada GroupData a nuestro repositorio de GitHub e incluir el nombre de esa entrada dentro de la llamada a la macro en lugar de GroupDataName. Consulta nuestra guía Barras laterales de referencia de API para obtener información sobre cómo hacerlo.

No añadas manualmente las macros de encabezado de estado. Consulta la sección "Cómo se añaden o actualizan los estados de las características" para añadir estos estados a la página.

Justo después de este bloque de nota se muestran ejemplos de los avisos de Contexto seguro, Disponible en workers, Experimental, Obsoleto y No estándar.

Compatibilidad con navegadores

Las páginas de inicio de la API pueden incluir, opcionalmente, una sección de compatibilidad con navegadores que muestra tablas de compatibilidad para una o más de las interfaces más importantes de la API. Si la compatibilidad es similar para la mayoría de las interfaces, generalmente basta con una sola tabla. Si la compatibilidad de toda la API es compleja o imposible de abarcar en unas pocas tablas, omite esta sección.

Para completar la sección de compatibilidad con navegadores, es posible que primero debas crear o actualizar entradas para las interfaces de API en nuestro repositorio de datos de compatibilidad con navegadores; consulta nuestra guía sobre cómo hacerlo.

Usa la macro {{Compat}} para añadir las tablas con la información de compatibilidad con navegadores.

Especificaciones

Las páginas de inicio de la API pueden incluir opcionalmente una sección de especificaciones que enumera las especificaciones relevantes para cada interfaz. A menudo, solo hay una especificación que abarca todas las interfaces de la API.

Para completar la sección de especificaciones, es posible que primero debas crear o actualizar entradas para las interfaces en el repositorio de datos de compatibilidad con navegadores para incluir los datos de especificación; consulta nuestra guía sobre cómo hacerlo.

Usa la macro {{Specifications}} para añadir las tablas con las especificaciones principales.

Recuerda eliminar toda esta nota explicativa antes de publicar

Contexto seguro: Esta función está disponible solo en contextos seguros (HTTPS), en algunos o todos los navegadores que lo soportan.

Nota: Esta característica está disponible en Web Workers.

Experimental: Esta es una tecnología experimental
Comprueba la Tabla de compabilidad de navegadores cuidadosamente antes de usarla en producción.

Obsoleto: Esta característica ya no se recomienda. Aunque es posible que algunos navegadores aún lo admitan, probablemente ya se ha eliminado de los estándares web relevantes, está en proceso de eliminación o solo se conserva por motivos de compatibilidad. Evite usarlo y actualice el código existente si es posible; consulte la tabla de compatibilidad en la parte inferior de esta página para orientar su decisión. Tenga en cuenta que esta característica puede dejar de funcionar en cualquier momento.

No estándar: Esta función no está estandarizada. No recomendamos usar funciones no estándar en producción, ya que tienen un soporte limitado en los navegadores y pueden cambiar o eliminarse. Sin embargo, pueden ser una alternativa adecuada en casos específicos donde no exista una opción estándar.

Comienza el contenido de la página con un párrafo introductorio: comienza nombrando la API y explicando qué hace. Idealmente, debería ser de una o dos oraciones breves.

Conceptos y uso

En esta sección, describe con un poco más de detalle el propósito y los casos de uso de la API: ¿por qué surgió la necesidad de crearla? ¿Qué problemas resuelve? ¿Qué conceptos involucra? ¿Cómo se usa, desde una perspectiva general?

No entres en muchos detalles en esta sección ni incluyas ejemplos de código. Si hay muchos conceptos que explicar sobre esta API, hazlo en un artículo aparte de "Fundamentos" o "Conceptos" (por ejemplo, Fundamentos de WebXR). Para una guía práctica de uso con ejemplos de código, incluye un artículo de "Uso…" en la documentación de tu API (por ejemplo, Uso de la API WebVR).

Guías

Incluye una lista de páginas de guías bajo esta página de inicio. Cada elemento de la lista debe enlazar a la página de la guía correspondiente. Esta sección es opcional; si solo hay una guía de "Uso", junto con algunas otras guías conceptuales, puede resultar más conveniente enlazarlas como un párrafo al final de la sección "Conceptos y uso". Esta sección puede ser más útil si hay tantas guías que la lectura se vuelve confusa.

Uso de la API ...

Párrafo introductorio de esta página de guía

Guía 2

Párrafo introductorio de esta página de guía

Interfaces

Para usar la macro domxref, elimina las comillas invertidas y la barra invertida en el archivo Markdown.

{{domxref("NameOfTheInterface")}}

Incluye una breve descripción de la interfaz y lo que hace. Incluye un término y una definición por cada interfaz o diccionario.

Extensiones a otras interfaces

Nombre de la interfaz extiende las siguientes API, añadiendo las características indicadas.

Interfaz 1

{{domxref("addition1")}}

Descripción de la característica de la Interfaz n.º 1 que se añade a esa API mediante la API que estás documentando actualmente. Un *término y definición por cada característica. Si esta API no extiende ninguna otra interfaz, puedes eliminar estas secciones.

Interfaz 2

{{domxref("addition1")}}

Descripción de la característica de la Interfaz n.º 2 que añade la API que estás documentando actualmente, etc.

Ejemplos

Ten en cuenta que usamos el plural "Ejemplos" incluso si la página contiene solo un ejemplo.

Un encabezado descriptivo

Cada ejemplo debe tener un encabezado H3 que lo identifique. El encabezado debe describir qué hace el ejemplo. Por ejemplo, "Un ejemplo simple" no dice nada sobre el ejemplo y, por lo tanto, no es un buen encabezado. El encabezado debe ser conciso. Para una descripción más larga, usa el párrafo que sigue al encabezado.

Consulta nuestra guía sobre cómo añadir ejemplos de código para obtener más información.

Nota: A veces querrás enlazar a ejemplos que están en otra página.

Escenario 1: Si tienes algunos ejemplos en esta página y otros más en otra página:

Incluye un encabezado H3 (###) para cada ejemplo de esta página y, al final, un último encabezado H3 (###) con el texto "Más ejemplos", bajo el cual puedes enlazar a los ejemplos de otras páginas. Por ejemplo:

md
## Examples

### Using the fetch API

Example of Fetch

### More examples

Links to more examples on other pages

Escenario 2: Si solo tienes ejemplos en otra página y ninguno en esta:

No añadas ningún encabezado H3; simplemente añade los enlaces directamente debajo del encabezado H2 "Examples". Por ejemplo:

md
## Examples

For examples of this API, see [the page on fetch()](https://example.org/).

Especificaciones

{{Specifications}}

Para usar esta macro, elimina las comillas invertidas y la barra invertida en el archivo Markdown.

Compatibilidad con navegadores

{{Compat}}

Para usar esta macro, elimina las comillas invertidas y la barra invertida en el archivo Markdown.

Véase también

Incluye enlaces a páginas de referencia y guías relacionadas con la API actual. Para más pautas, consulta la sección Véase también en la Guía de estilo de redacción.

  • enlace1
  • enlace2
  • enlace_externo (año)

Help improve MDN

Learn how to contribute

This page was last modified on by MDN contributors.

View this page on GitHub • Report a problem with this content