Compartir a través de

Estructura de archivos y carpetas wiki en Git

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

En este artículo se describen los archivos y la estructura de carpetas para wikis aprovisionadas y wikis publicadas como código. Para ambos tipos de wiki, los archivos se almacenan en un repositorio de Git. Los archivos pueden incluir páginas de Markdown, código, imágenes, datos adjuntos u otros artefactos. Para establecer la secuencia de presentación de los archivos, Git agrega un archivo especial (.order) en cada carpeta del repositorio.

Al crear un proyecto, una wiki no se crea de forma predeterminada. Puede configurar una wiki, crear un archivo léame o publicar el código del proyecto como una wiki.

La wiki se crea mediante la interfaz de usuario de Azure DevOps. A continuación, puede editar la wiki desde la ruta de acceso url del repositorio de Git.

Archivos de repositorio y estructura de carpetas

El repositorio git de una wiki tiene dos convenciones de nomenclatura:

  • El nombre del repositorio wiki es <ProjectName>.wiki donde <ProjectName> es el nombre de tu proyecto.
  • El nombre de la rama raíz del repositorio wiki es wikiMain.

Puede administrar un repositorio wiki de la misma manera que administra otros repositorios de Git mediante la definición de directivas de rama en la wikiMain rama. También puede realizar cambios en la rama local wikiMain e insertarlos directamente en la rama remota sin definir ninguna directiva.

Un repositorio wiki consta de los siguientes archivos y carpetas:

  • Un archivo para cada página de Markdown ubicada en el nivel raíz
  • Un archivo denominado .order ubicado en el nivel raíz y también dentro de cada subcarpeta
  • Una subcarpeta para cada página wiki que tenga subpáginas
  • Una carpeta denominada .attachments para almacenar todos los datos adjuntos usados en la wiki

Convenciones de nomenclatura de archivos

El nombre de archivo de cada página wiki corresponde al título de la página wiki. En el nombre de archivo, un guión (-) representa un espacio en el título de la página. Por ejemplo, el título de página "Cómo contribuir" corresponde al nombre de archivo How-to-contribute.md. La ruta de acceso url a la página wiki incluye el nombre de archivo. Por ejemplo: https://github.com/ExampleWiki/How-To/How-to-contribute.md. Este enfoque ayuda a garantizar que los vínculos de marcador a la página permanezcan intactos a medida que cambia la wiki a lo largo del tiempo.

Cada página wiki corresponde a un archivo en el repositorio de Git wiki. Las restricciones siguientes se aplican a los nombres de archivo de página y al tamaño del archivo:

  • Nombre de archivo: al elegir un nombre para el archivo de página, tenga en cuenta que la ruta de acceso completa al archivo debe tener 235 caracteres o menos. La ruta de acceso completa a la página consta de la dirección URL del repositorio, la ruta de acceso de carpeta al archivo de página y el nombre del archivo de página. Por ejemplo: https://github.com/ExampleWiki/Contributors/Code/How-to-add-code-to-the-project.md.

  • Unicidad: el nombre del archivo de página debe ser único dentro de su ubicación de carpeta en la jerarquía del repositorio wiki. El nombre es sensible a mayúsculas y minúsculas.

  • Caracteres especiales: el nombre del archivo de página tiene restricciones sobre los siguientes caracteres especiales:

    • Sin caracteres de control Unicode ni caracteres suplentes
    • Sin caracteres imprimibles: barra diagonal /, barra diagonal inversa \, hash #
    • Ningún símbolo de punto . al principio o al final del nombre

  • Tamaño del archivo: el tamaño máximo del archivo de página es de 18 MB.

  • Tamaño del archivo adjunto: el tamaño máximo de los datos adjuntos a un archivo de página es de 19 MB.

Caracteres especiales permitidos

En un nombre de archivo de página se pueden incluir varios caracteres especiales, como los dos puntos : y el guion -. Por ejemplo, podría asignar un nombre a un archivo Markdown como faq:0525 o Setup-Guide.

Importante

Para evitar errores en la sintaxis de página y la navegación del explorador, no use el carácter de espacio ( ) en los nombres de archivo de página. Si asigna un nombre a los archivos de página en función del título de la página, reemplace los espacios del título de la página por un guion (-) en el nombre de archivo.

En la tabla siguiente se enumeran los caracteres especiales permitidos en los nombres de archivo de página wiki y la cadena codificada en URI correspondiente:

Carácter Símbolo Cadena de URI
Colon : %3A
Corchete angular izquierdo < %3C
Corchete angular derecho > %3E
Asterisco (comodín) * %2A
Signo de interrogación ? %3F
de canalización de | %7C
Guión (guión) - %2D
Comilla doble " %22

Por ejemplo, el nombre de archivo FAQ:0525 se codifica como FAQ%3A0525.

Secuencia de páginas y el archivo .order

El archivo .order define la secuencia de página wiki. Git busca este archivo en cada carpeta para identificar la secuencia para presentar archivos en esa ubicación. La secuencia de página predeterminada es orden alfabético (A a Z) por nombre de archivo.

Importante

Cuando una carpeta primaria contiene solo subcarpetas y ningún archivo propio, la wiki muestra la carpeta primaria como en blanco, incluso si las subcarpetas incluyen archivos markdown. Para garantizar la visibilidad de los archivos markdown dentro de las subcarpetas, coloque siempre al menos un archivo (como un .order archivo o cualquier otro archivo con contenido) en la carpeta primaria.

|- parent-folder
|-- sub-folder1
|   |-- file1.md
|   |-- file2.md
|-- sub-folder2
|   |-- file3.md
|   |-- file4.md
|-- .order

Definición de una secuencia de páginas personalizada

Cuando una carpeta no tiene un archivo .order , Git usa la secuencia alfabética predeterminada.

Puede definir una secuencia personalizada para cualquier carpeta actualizando el archivo .order de la carpeta, incluido en el nivel raíz.

El objeto visual siguiente muestra un ejemplo de una tabla wiki de contenido (TOC) y el archivo .order correspondiente que crea el TOC.

Wiki TOC se muestra en el explorador web

Captura de pantalla del TOC para una wiki con varias carpetas expandidas para mostrar subcarpetas.

El archivo .order define la secuencia de páginas TOC

Captura de pantalla de una carpeta wiki y una lista de archivos en un repositorio de Git. El archivo .order está abierto y muestra la definición de la secuencia de páginas TOC.

El archivo .order cambia la secuencia de alfabética a "Marketing" seguida de "Fabrikam Fiber".

Para obtener más información sobre cómo reordenar páginas wiki, vea Agregar, editar y reordenar páginas wiki.

Restaurar secuencia alfabética

Si una carpeta tiene una secuencia personalizada, puede revertir el método de ordenación alfabético siguiendo estos pasos:

  1. Copie la dirección URL de clonación de la wiki y ábrala en un explorador. Se abre el repositorio de Git para la wiki.

  2. Vaya al archivo .order que desea revertir y eliminar el archivo. Una vez eliminado el archivo, Git crea automáticamente un nuevo archivo .order para esa ubicación. El nuevo archivo usa la secuencia predeterminada.

Contenido relacionado

  • Last updated on