Show last authors
1 = Table of Contents =
2
3 {{toc numbered="true"/}}
4
5
6
7
8 = Project Idea =
9
10 The idea of this project is to develop an XWiki Extension which will convert GitHub pages into XWiki pages using the Filter Application.
11
12 = Initial Requirements =
13
14 Evaluated after talking about use cases and requirements on the forum post.
15
16 == Import from a GitHub Wiki repository ==
17
18 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).
19
20 == Main Repository ==
21
22 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.
23
24 == Ability to pass an oauth token ==
25
26 Make the import process accept a oauth token to perform the fetching of the GitHub repo. This allows to support private repos.
27
28 == Provide a simplified Import UI ==
29
30 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.
31
32 = Optional Requirements =
33
34 == Convert Syntax ==
35
36 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).
37
38 == Merge Wiki ==
39
40 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.
41
42 == Two-way sync ==
43
44 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:
45
46 * Remembering the list of imported pages and their content.
47 * Writing an XWiki EventListener for auto-sync.
48 * Having an XWiki UI to display changes since the last import with ability to see the diffs.
49
50 == Support offline importing ==
51
52 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.
53
54 = Architectural Design =
55
56 [[image:MainArchitecture.png||alt="Architecture Design for GitHub Importer"]](% id="cke_bm_176S" style="display:none" %)
57
58 (% class="wikigeneratedid" %)
59 Input Filter -> GitHub Wiki Repository -> Clone -> Read Sidebar -> Create XWiki Structure -> Convert Pages -> Create XWiki Pages -> Save Pages to XWiki.
60
61 == Wiki Structure Flow chart ==
62
63 [[image:https://design.xwiki.org/xwiki/bin/download/Proposal/GitHubImporter/StructureSidebar.png?rev=1.1]]
64
65 Sidebar exists -> Read Sidebar -> Create Wiki Structure -> Align pages according to the structure -> Create XWiki pages.
66 \\-To be updated-

Get Connected