Publicación de un repositorio de Git en una wiki

  • Artículo

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Puede publicar contenido que ya mantiene en un repositorio de Git en una wiki. Por ejemplo, este contenido podría ser compatibilidad con el kit de desarrollo de software (SDK), documentación del producto o un archivo LÉAME. También puede publicar varias wikis en un solo proyecto de equipo.

Al publicar los archivos de Markdown en una wiki, obtendrá las siguientes ventajas:

  • Organización del contenido en una estructura jerárquica de página
  • Examinar y filtrar la tabla de contenido
  • Publicar nuevas versiones del contenido
  • Administrar el contenido de la misma manera que administra la base de código
  • Buscar en la wiki fácilmente mediante la característica de búsqueda wiki

Para obtener más información, consulte Código aprovisionado frente a código publicado como wiki.

Sugerencia

Puede agregar y editar contenido que publicó en una wiki mediante los pasos descritos en este artículo. También puede trabajar sin conexión y actualizar contenido wiki de la misma manera que colabora en el código a través de un repositorio de Git. Para obtener más información, vea Actualizar páginas wiki sin conexión.

Requisitos previos

  • Tener un proyecto de equipo. Si no tiene uno, cree un proyecto ahora.
  • Habilite el servicio Azure Repos para el proyecto.
  • Tener un repositorio de Git definido en el proyecto de equipo. Idealmente, este repositorio contiene al menos un archivo Markdown, que quiere publicar en la wiki. Para obtener más información, consulte Creación de un nuevo repositorio de Git en el proyecto.
  • Tener el permiso Contribuir para publicar código como wiki. De forma predeterminada, este permiso se establece para los miembros del grupo Colaboradores. Cualquier persona que tenga permisos para contribuir al repositorio de Git puede agregar o editar páginas wiki.

Abrir wiki

  1. Inicie sesión en su organización (https://dev.azure.com/{yourorganization}), abra el proyecto y seleccione Wiki de información general>.

    Captura de pantalla que muestra la selección de la pestaña wiki.

Si necesita cambiar de proyecto, seleccione Azure DevOps para examinar todos los proyectos.

Publicación de un repositorio de Git en una wiki

Realice los pasos siguientes al mantener archivos Markdown en un repositorio de Git existente y quiera publicarlos en una wiki.

  1. Seleccione Publicar código como wiki.

    Captura de pantalla que muestra el botón resaltado Publicar código como wiki.

    Nota:

    La opción Publicar código como wiki no aparecerá si el proyecto no tiene definido un repositorio de Git. Cree un nuevo repositorio de Git y, a continuación, devuelva y actualice esta página.

  2. Si ya ha aprovisionado una wiki de proyecto de equipo, seleccione Publicar wiki de código.

    Captura de pantalla que muestra la opción de menú Publicar código como wiki.

  3. Elija el repositorio, la rama y la carpeta que contienen los archivos Markdown y escriba un nombre para el repositorio wiki. El repositorio de Git debe estar dentro del proyecto de equipo.

    Captura de pantalla que muestra el nombre especificado para el repositorio wiki.

    Especifique la raíz del repositorio cuando quiera publicar todos los archivos Markdown del repositorio en la wiki.

  4. Seleccione Publicar. El repositorio wiki se rellena con los archivos y carpetas markdown incluidos en el repositorio seleccionado.

    Por ejemplo, en la imagen siguiente se muestra el repositorio publicado de los archivos contenidos en el repositorio azure-docs-sdk-node que seleccionó en el paso 2.

    Captura de pantalla de wiki publicada de archivos Markdown del repositorio existente.

    La tabla wiki de contenido (TOC) contiene los siguientes archivos:

    • Cada archivo Markdown (tipo de archivo= .md) definido en el repositorio,rama/carpeta aparece en orden alfabético, el título toC se deriva del nombre de archivo Markdown.

    • Una página principal para cada subcarpeta definida dentro de la carpeta publicada, incluso si no contiene ningún archivo Markdown.

      En la imagen siguiente se muestra el contenido del repositorio azure-docs-sdk-node.

      Captura de pantalla del repositorio con archivos Markdown publicados en wiki.

El encabezado de la rama del repositorio de Git se asigna a la wiki. Los cambios realizados en la rama y las carpetas seleccionadas se reflejan automáticamente en la wiki. No hay otros flujos de trabajo implicados.

Nota:

Puede publicar hasta 10 ramas por wiki de código publicado.

Para la wiki aprovisionada con los archivos de Markdown adicionales, puede agregar o editar páginas de la misma manera que mantiene el código en el repositorio de Git.

Editar, cambiar el nombre o eliminar páginas

Siga estos pasos para editar, cambiar el nombre o eliminar una página wiki.

  1. En el proyecto, abra Archivos de repositorios>o Archivos de código.>

  2. Elija la página que desee, seleccione Acciones y, a continuación, elija la operación.

    Captura de pantalla de las opciones de acción wiki, Editar, cambiar nombre o eliminar.

Nota:

Administre el repositorio wiki de la misma manera que administra cualquier otro repositorio de Git mediante la definición de directivas de rama en la rama que seleccionó para publicar en una wiki. Sin embargo, sin ninguna directiva definida, puede realizar cambios e insertarlos directamente en la rama desde el portal web o desde un cliente.

Edición de una página de Pages

Use los vínculos disponibles en modo de edición para obtener una vista previa de los cambios o resaltar los cambios realizados en la versión anterior. Para descartar los cambios, seleccione Cancelar. Para obtener más información sobre las características de Markdown admitidas, consulte Instrucciones de sintaxis para el uso de Markdown.

  1. Cuando haya terminado, agregue un comentario sobre las actualizaciones y seleccione Confirmar.

    Captura de pantalla del cuadro de diálogo Confirmar.

    El sistema le presenta automáticamente un vínculo para crear una solicitud de incorporación de cambios. Puede omitir este mensaje cuando edite directamente la rama wiki.

    Captura de pantalla del vínculo Crear una solicitud de incorporación de cambios.

Sugerencia

Al cambiar el nombre o el caso de un archivo, actualice el .order archivo para reflejar el cambio. Para obtener más información, vea Cambiar la secuencia de páginas, agregar o actualizar un archivo .order.

Cambiar el nombre de una página

Todas las páginas que desea que aparezcan en el TOC deben ser el tipo .mdde archivo .

  1. Seleccione Cambiar nombre para cambiar el nombre del archivo en consecuencia.

Por ejemplo, en la siguiente imagen, cambiamos el nombre de new-home-page.md a New-Home-Page.md. Esta página aparece en el TOC con la etiqueta "Nueva página principal".

Captura de pantalla del cuadro de diálogo Cambiar nombre de confirmación.

Los títulos de página distinguen mayúsculas de minúsculas y deben ser únicos dentro de la carpeta y 235 caracteres o menos. Para obtener más información sobre otras restricciones de título, consulte Restricciones de nomenclatura de títulos de página.

Eliminar una página

Puede eliminar los archivos Markdown que no quiera que aparezcan en la wiki de la carpeta publicada. Si incluyó el archivo en un .order archivo, elimine su entrada del .order archivo. Para obtener más información, vea Cambiar la secuencia de páginas, agregar o actualizar un archivo .order.

Agregar una página o páginas

Puede agregar las páginas siguientes a la wiki publicada:

  • Agregar un archivo a una carpeta raíz o una subcarpeta desde el portal web
  • Carga de archivos en una carpeta raíz o una subcarpeta
  • Agregar o actualizar un .order archivo para especificar la secuencia de páginas en el TOC wiki

Cada actualización requiere que confirme los cambios en el repositorio. A continuación, puede actualizar la wiki del repositorio publicado para revisar los cambios.

Adición de una página desde el portal web

  1. En Archivos de repositorios>o Archivos de código>para el repositorio publicado, seleccione Acciones y, a continuación, elija Archivo.

    Captura de pantalla de la adición de una página a la wiki desde el portal web.

  2. Escriba un nombre para la página y asegúrese de especificar el tipo de .md archivo. El nombre de archivo debe corresponder al título de página que desea que aparezca en el TOC, con guiones en lugar de espacios. Especifique un título único de 235 caracteres o menos. Los títulos de página distinguen mayúsculas de minúsculas. Para obtener más información sobre otras restricciones de título, consulte Restricciones de nomenclatura de títulos de página.

    Por ejemplo, para agregar una página que aparece en el TOC como página 4, agregue un archivo denominado Page-4.md.

    Captura de pantalla que muestra el cuadro de diálogo Nuevo archivo con el botón Crear.

  3. Escriba el contenido de la página. Para obtener más información, consulte Instrucciones de sintaxis para archivos, widgets, wikis y comentarios de solicitud de incorporación de cambios.

  4. Cuando haya terminado, seleccione Confirmar.

Cargar archivos a una carpeta

  1. Si ya ha definido el contenido existente, puede cargarlo en una carpeta. Seleccione Acciones y, a continuación, elija Cargar archivos.

    Captura de pantalla que muestra la selección resaltada, Cargar archivos.

  2. Complete el formulario de cuadro de diálogo Confirmar y seleccione la carpeta y los archivos que desea cargar.

    Captura de pantalla que muestra el cuadro de diálogo Confirmar para cargar archivos.

Agregar una página principal y subpáginas

Para agregar una página primaria, agregue primero un archivo Markdown en el nivel de carpeta raíz y, a continuación, agregue una carpeta con la misma etiqueta.

  1. Para agregar una carpeta, seleccione Carpeta y, a continuación, complete el formulario de diálogo Nueva carpeta . Especifique al menos un archivo para que se corresponda con una subpágina de la carpeta .

    Captura de pantalla del cuadro de diálogo Crear carpeta.

  2. Agregue todos los archivos que desee como subpáginas a la carpeta.

Agregar o actualizar un archivo .order

El último paso al agregar archivos o carpetas al repositorio wiki es agregar o actualizar el .order archivo de las carpetas actualizadas. Esta acción refleja la secuencia de páginas que desea mostrar en el TOC. Para obtener más información, vea Cambiar la secuencia de páginas, agregar o actualizar un archivo .order. Los archivos que no aparecen en el .order archivo se agregan al final de la lista alfabética, ya que su orden se establece int.MaxValueen .

Cambiar la secuencia de páginas, agregar o actualizar un archivo .order

Cada .order archivo define la secuencia de páginas contenidas en una carpeta. El archivo raíz .order especifica la secuencia de páginas definidas en el nivel raíz. Para cada carpeta, un .order archivo define la secuencia de subpáginas agregadas a una página primaria.

  1. Puede agregar un .order archivo de la misma manera que agregue cualquier archivo desde la página Archivos de código>. Asigne al archivo el nombre .order.

  2. Edite el contenido del archivo para reflejar la secuencia de archivos Markdown contenidos en la carpeta. Cada entrada debe reflejar el nombre de archivo, pero sin el tipo de .md archivo. Los títulos distinguen mayúsculas de minúsculas, por lo que la entrada debe coincidir con el caso usado en el nombre de archivo.

Por ejemplo:

README
page-2
page-3
Page-4
Misc content

Establecer una página principal

De forma predeterminada, el primer archivo que aparece en la raíz dentro del orden alfabético se establece como la página principal wiki. Al seleccionar Wiki en el portal web, se abre la página principal.

  1. Cambie la página principal estableciendo la secuencia de páginas en el archivo raíz .order .

Por ejemplo, escriba el nombre de la página en la primera línea.

New home page name here
page-2
page-3
Page-4
README
Misc content

Promover carpeta a página

Para que una carpeta también sea una página, necesita un archivo Markdown con el mismo nombre que la carpeta, establecido como relacionado en la carpeta. Por lo tanto, tanto la carpeta como el .md archivo del mismo nombre deben estar junto al otro.

Como se muestra en el ejemplo siguiente, Test tiene una carpeta y un .md archivo, que crea una jerarquía dentro del árbol wiki.

Captura de pantalla que muestra la promoción de una carpeta a una página.

Selección de una versión wiki

Para seleccionar una versión wiki, elija la versión de las opciones de rama en la página wiki.

Captura de pantalla que muestra una versión wiki seleccionada en el menú desplegable wiki.

Anulación de la publicación de una wiki de código

Si ya no desea que un repositorio se publique como wiki, puede optar por anular su publicación.

Advertencia

Al anular la publicación de una wiki, se anula la publicación de todo el código wiki, que incluye todas las versiones del repositorio que ha publicado anteriormente.

  1. Seleccione la wiki que desea cancelar la publicación, abra el menú contextual y seleccione Unpublish wiki (Anular publicación).

    Captura de pantalla del cuadro de diálogo Despublicar una confirmación wiki.

  2. Para confirmar que desea cancelar la publicación de la wiki, elija Anular publicación.

    Captura de pantalla de la wiki de cancelación de la publicación.