Clone and update wiki content offline

VSTS | TFS 2018

The wiki created for a team project employs a Git repository to store pages, images, attachments, and the sequence of pages and sub-pages. To update your wiki pages offline, you must first clone your wiki repository and add or edit pages much the same way you develop code in a Git repo. You can then push your changes to your working branch and merge them with the master branch of the wiki repository.

Here we show the web portal Files page for the Fabrikam Fiber.wiki repo.

Wiki Master files

You can use any client you want or git command line tools to update your wiki offline. For details on working with Git repositories and supported tools, see Git Repositories.

The basic steps to update wiki content offline are:

  1. Clone your wiki Git repo to your local IDE or workspace
  2. Add files or folders to your local git branch
  3. Update the .order file(s) to reflect the pages and sub-pages that you've added
  4. Commit and push the updates you made to your local git branch.

You can perform these steps to migrate markdown pages from another wiki to your team project wiki or to content that you publish as code to a wiki. In order to perform these steps, you'll want to understand the underlying structure of your wiki Git repo. For details, see Wiki Git repository files and file structure. To understand how to manage the different wiki types, see Differences between provisioned wiki and publish code as wiki.

You can perform these steps to migrate markdown pages from another wiki to your team project wiki. In order to perform these steps, you'll want to understand the underlying structure of your wiki Git repo. For details, see Wiki Git repository files and file structure.

Clone your wiki

  1. To clone a wiki Git repository, open the More context menu and choose Clone wiki.

    Clone wiki Git repository

  2. From the Clone repo dialog, click the copy-clone icon.

    Copy the wiki url

    You can enter it in your browser to view the files defined under the wikiMaster branch.

    Wiki Master files

  3. Use the URL that you copied to clone the repo in the IDE that you use. To learn more, see one of these articles:

Add pages to your local Git repository

You author pages using markdown format. Add a markdown file for each page and sub-page that you want to add to your wiki to your local branch.

Add pages

To add pages at the root of the wiki tree, add a markdown file at the root of the Git repository.

  1. For each page you want to add, create a markdown file with the page contents and add it under the root folder for your repo.

    For the Fabrikam Fiber team project, this will be under the following folder:

    C:\Users\UserName\Source\Repos\Fabrikam Fiber.wiki

  2. To add pages at the root of the wiki tree, add a markdown file for each page at the root of the Git repository.

    Local branch wiki Git repo

  3. After you've added all the pages you want to add at the root, update the .order file at the root. This file should contain one entry for each markdown file that is defined at the root. Each entry should match the file title with spaces replaced with a dash.

    For example:

    Welcome 
    Roadmap  
    How-to-contribute  
    Home  
    Reference  
    

Add sub-pages

  1. To add sub-pages, create a folder for the parent page, and then add markdown files for each sub-page in the folder.

    For example, here we show four files added to the How-to-contribute folder. These sub-pages will appear under the How to contribute page in the wiki.

    Local branch wiki Git repo

  2. Next, add a .order file in the folder with the order of the sub-pages as they should appear in the wiki. To understand the use of the .order file to sequence pages, see Wiki Git repository files and file structure.

    Keeping with our example, the contents of this file will contain:

    Request-extensions  
    Licensing  
    Smoke-test  
    Coding-guidelines  
    

Push your changes

  • When done with all your updates, push the files to the Git repository.

    The pages and sub-pages you added will appear immediately in your wiki.

    Wiki tree updated

    If there are any errors in the process, the pages will appear in your wiki with a warning sign.

    Warning when .order file is not updated properly