GitHub Importer

Last modified by Vincent Massol on 2024/02/26 17:53

 XWiki
 Requirements
 Completed
 
 

Description

Table of Contents

  1. Table of Contents
  2. Project Idea
  3. Initial Requirements
    1. Import from a GitHub Wiki repository
    2. Main Repository
    3. Ability to pass an oauth token
    4. Provide a simplified Import UI
  4. Optional Requirements
    1. Convert Syntax
    2. Merge Wiki
    3. Two-way sync
    4. Support offline importing
  5. Architectural Design
    1. Wiki Structure Flow chart

Project Idea

The idea of this project is to develop an XWiki Extension which will convert GitHub pages into XWiki pages using the Filter Application.

Initial Requirements

Evaluated after talking about use cases and requirements on the forum post.

Import from a GitHub Wiki repository

Instead of creating each page on XWiki Platform, user will be able to simply provide the GitHub repository with Wiki and let the Filter Application convert it to XWiki pages and save them inside XWiki according to the Sidebar (if provided).

Main Repository

A wiki repository is different from the main repository. It can be cloned via .wiki.git. Some users may provide the main <repository>.git, so the extension will automatically fix the link to improve UX.

Ability to pass an oauth token

Make the import process accept a oauth token to perform the fetching of the GitHub repo. This allows to support private repos.

Provide a simplified Import UI

The Filter Stream app provides a generic UI but it’s complex and not very user-friendly. This app should provide a simplified UI geared towards importing GitHub pages.

Optional Requirements

Convert Syntax

Convert the pages written in the GitHub-flavored Markdown markup to XWiki Syntax 2.1. Also provide an option to decide to do this conversion or not (if users want to use them in MD in XWiki they should be able to do so).

Merge Wiki

In this use case, if the wiki is re-imported, it merges the changes inside the pages so the new page will be shown merged instead of overwritten.

Two-way sync

If the project is done early and if there’s enough time, it would be interesting to support round-tripping and be able push changes done in XWiki on the imported pages back to GitHub (either by git pushing or by using a GitHub REST API). Specifically this means:

  • Remembering the list of imported pages and their content.
  • Writing an XWiki EventListener for auto-sync.
  • Having an XWiki UI to display changes since the last import with ability to see the diffs.

Support offline importing

User will be able to use a .zip file containing the wiki repo, as an input to the GitHub Importer and get them into XWiki as XWiki pages.

Architectural Design

Architecture Design for GitHub Importer

Input Filter -> GitHub Wiki Repository -> Clone -> Read Sidebar -> Create XWiki Structure -> Convert Pages -> Create XWiki Pages -> Save Pages to XWiki.

Wiki Structure Flow chart

https://design.xwiki.org/xwiki/bin/download/Proposal/GitHubImporter/StructureSidebar.png?rev=1.1

Sidebar exists -> Read Sidebar -> Create Wiki Structure -> Align pages according to the structure -> Create XWiki pages.

-To be updated-


 

Tags:
    

Get Connected