UI to import GitHub pages into wiki pages

Description

A User-friendly Interface to import GitHub pages as wiki pages into XWiki using GitHub Importer Filter.

Usage

1. Open GitHub Importer from the Applications Panel.

   

2. Fill the fields with your values.
   • Source Type: The source can be a URL (online) or a File (offline) types.
   • URL: Link (URL) to the GitHub pages/wiki repository to import. This need internet connection.

     Some interesting GitHub pages/wiki examples that you could try out:

     • GitHub Wikis
       • Nebulasio wiki. Use the https://github.com/nebulasio/wiki.wiki.git value for the source.
       • MIXXXDJ wiki. Use the https://github.com/mixxxdj/mixxx.wiki.git value for the source.
     • GitHub Pages
       • Kbroman's simple github pages website. Use the https://github.com/kbroman/simple_site.git value for the source.
       • Open Tech School github pages website. Use the https://github.com/OpenTechSchool/www.opentechschool.org.git value for the source.
       • beta.gouv.fr. Use the https://github.com/betagouv/beta.gouv.fr.git value for the source.
   • Path (in case of File/Directory): The path/reference to the file (zip) or directory (an already cloned repository) in your storage.
   • Parent Page: The root of the pages to be imported, to keep them in a defined space. In case of existing parent, add a child. For example: ExistingPage.ChildPage.
   • Authenticator: The token / oauth / username of the GitHub user to clone repositories which are not public.
   • Password: The password of the GitHub user (Only needed if you are using the Authenticator with Username).
   • Convert to Default Syntax: Converts the GitHub pages written in GitHub-flavored Markdown syntax into Default syntax (set in Administration / Editing / Syntaxes). If not checked, then the content is not converted and the page is set to use the GitHub-Flavored Markdown Syntax 1.0 (markdown+github/1.0). Note that this syntax is still in development.
   • Create Hierarchy of Pages: Imports and saves the pages hierarchically in XWiki according to their level defined in Sidebar (_Sidebar.md) since GitHub do not support hierarchy.

     Make sure you define a supported hierarchy. See some examples:

     • Simple hierarchy: Haxsen's simple sidebar wiki
     • Complex hierarchy: Nebulasio wiki (includes other repository links which are then cloned as well).
     • Complex hierarchy: MIXXX DJ wiki
       Simple hierarchy is recommended since the point of this option is to create XWiki pages in a hierarchical manner inside XWiki. A simple Sidebar can do this with minimum effort for users.
       Other Sidebars (such as complex examples) are also supported but in case you encounter an error, please edit the Sidebar (like the examples) so the GitHub Importer can read the Sidebar correctly.
3. Click the Import button.

   

   Wait for the import to finish. If the import fails, check the Job log to see where the error occurs from. Report that issue on GitHub Importer JIRA if you think it is the extension's problem.
   If the import is successful, new pages will be created in your XWiki. Click on See the output. below Import Information, or open the Job log and check where the pages have been created.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

1. Log in the wiki with a user having Administration rights
2. Go to the Administration page and select the Import category
3. Follow the on-screen instructions to upload the downloaded XAR
4. Click on the uploaded XAR and follow the instructions
5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Release Notes

v1.6

v1.5

v1.4

v1.3

v1.2

v1.1

Dependencies

Dependencies for this extension (org.xwiki.contrib.github-importer:github-importer-ui 1.6):

• org.xwiki.contrib.github-importer:github-importer-filter 1.6
• org.xwiki.platform:xwiki-platform-filter-script 12.4
• org.xwiki.platform:xwiki-platform-rendering-macro-velocity 12.4
• org.xwiki.platform:xwiki-platform-rendering-macro-include 12.4
• org.xwiki.rendering:xwiki-rendering-macro-html 12.4
• org.xwiki.platform:xwiki-platform-panels-ui 12.4