JarCastingAEM Importer for Markdown
Imports Markdown documents into AEM, creating an AEM content package on the go.
Why would you want this?
If you have a bunch of Markdown files, for instance API documentation generated from JSON Schema, or technical documentation that you want to publish on an AEM-powered web site, for instance Adobe I/O. Your Markdown files are not hosted on Github.com, so you cannot use the built-in Markdown importer in Adobe I/O, but with this program you can include the Markdown to AEM conversion into your Continuous Integration process.
Prerequisites
This is a Java application, so you need Java 8 or higher installed on your system.
$ java -version
java version "1.8.0_121"
Java(TM) SE Runtime Environment (build 1.8.0_121-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.121-b13, mixed mode)
If you want to build this project from source (right now, that's required), you will also need Maven 3.
$ mvn -v
Apache Maven 3.3.9 (bb52d8502b132ec0a5a3f4c09453c07478323dc5; 2015-11-10T17:41:47+01:00)
Maven home: /usr/local/Cellar/maven/3.3.9/libexec
Java version: 1.8.0_121, vendor: Oracle Corporation
Java home: /Library/Java/JavaVirtualMachines/jdk1.8.0_121.jdk/Contents/Home/jre
Default locale: en_US, platform encoding: UTF-8
OS name: "mac os x", version: "10.12.6", arch: "x86_64", family: "mac"
Getting Started
Building from Source
To use the application, check out this source code, then build with Maven:
$ mvn clean package
If you are using Adobe's default settings.xml and you are outside of Adobe's VPN, it is a good idea to disable the default profile:
$ mvn clean package -P \!artifactory-corp
You will end up with a file called target/importer-with-dependencies.jar.
Creating an AEM Content Package
Run the application using java -jar and pass in a configuration file:
$ java -jar target/importer-jar-with-dependencies.jar markdown2AEM.yml
This will create a file importerDemo.zip, which you can install in your AEM instance using the package manager or curl command.
curl -u userid:password -F file=@"importerDemo.zip" -F name="importerDemo.zip" -F force=true -F install=true http://localhost:port/crx/packmgr/service.jsp
Configuration
All configuration happens in a .yaml file. This configuration file specifies where to find the Markdown files, where the content should be put in AEM and what kind of content should be created.
There are two configuration modes:
- Integrated GitHub Client: the importer will pull all files from GitHub (Enterprise)
- Local Checkout: the importer assumes you have all files in a local checkout
Integrated GitHub Client
following settings exist for the integrated GitHub client:
githubUrl: hostname of your GitHub instancegithubContentUrl: API endpoint for retrieving binaries from GitHubgithubApiUrl: hostname of the GitHub API serverapiToken: the API token to access GitHub. Get it from GitHub -> Settings -> Personal access tokens -> Generate new tokencommitTime: TODOrepositoryUrl: URL of the repository you want to accessprivateRepository: settrueif this is a private repositorybranches: a list of branches or tags that will be imported. This is useful when you have multiple API versions that need to be documented in parallel.
Example Configuration
githubUrl: github.com
githubContentUrl: https://raw.githubusercontent.com
githubApiUrl: api.github.com
# don't put your API token on GitHub. Use read-only tokens.
apiToken: cafea1b0c6faee11d6dcbabef838f2abcdec6feac
commitTime: 1
repositoryUrl: https://github.com/iotester/importerTest
privateRepository: false
branches:
- master
- develop
Local Checkout
The local checkout is ideal when you are working with a CI system that already has your Git credentials. You don't need to generate an API token, you just call git export or git clone in your build script before calling importer.jar.
Following settings are available for local checkout:
githubUrl: hostname of your GitHub instancerepositoryUrl: URL of the repsoitory, in case you want to enable the "edit on GitHub link"branches: a list of branches or tags that will be imported. This is useful when you have multiple API versions that need to be documented in parallel.workingDirs: a map of branch names to local checkout directories. Both absolute and relative path names are acceptable
Example Configuration
repositoryUrl : https://github.com/iotester/importerTest
privateRepository : false
branches:
- master
- develop
#if working dirs are set then api import will be skipped
workingDirs :
- master:./exports/master
- develop:./exports/develop
Contributing
This application is work in progress and we are happy about any contribution. You can
- make a pull request on GitHub
- file an issue against the APM project in jira.adobe.com
- just say hi in the
#www_adobe_iochannel on Slack (Enterprise Grid)
Releasing
This project is configured to deploy to Maven Central via Sonatype OSS. If you want to release yourself, first create an account in the Sonatype JIRA and open a new issue, requesting access to the group com.adobe.aem. Please reference trieloff and adobe-bot in your request, so that we can confirm your permission.
In the next step, edit your ~/.m2/settings.xml to include a new <server> section:
<settings>
<servers>
<server>
<id>ossrh</id>
<username><!-- your Sonatype username --></username>
<password><!-- your Sonatype password --></password>
</server>
</servers>
</settings>
Deploying a Build
To deploy a build, use the pre-configured Maven Release Plugin with following commands:
$ mvn release:clean release:prepare
$ mvn release:perform
Releases can only be performed when you
- have commit permissions on this repository
- have access to the Sonatype group
License/Copyright
Copyright 2017 Adobe Systems Incorporated. All rights reserved. This file is licensed to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
