GitHub Importer
Description
Table of Contents
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
Input Filter -> GitHub Wiki Repository -> Clone -> Read Sidebar -> Create XWiki Structure -> Convert Pages -> Create XWiki Pages -> Save Pages to XWiki.
Wiki Structure Flow chart
Sidebar exists -> Read Sidebar -> Create Wiki Structure -> Align pages according to the structure -> Create XWiki pages.
-To be updated-