JarCastingAlexandria
Integrate markdown docs with antiquated html document hosting platforms using standard Java build tools.
Alexandria bring CI concepts to document hosting platforms which dont integrate with the tools and processes we have grown reliant on. Keep your documents with your source code in friendly markdown and let Alexandria convert and sync them as part of your project's build process.
Any platform which offers a rest API can be added to the project by implementing an interface for creating, updating and deleting documents. Alexandria handles the rest.
$ mvn deploy
[INFO] Scanning for projects...
[INFO]
[INFO] ----------------< com.github.macgregor:alexandria-demo >----------------
[INFO] Building alexandria-demo 0.1.2
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- alexandria-maven-plugin:0.1.2:index (alexandria) @ alexandria-demo ---
[INFO] Matched 4 files (1 indexed, 3 already indexed)
[INFO]
[INFO] --- alexandria-maven-plugin:0.0.6-SNAPSHOT:convert (alexandria) @ alexandria-demo ---
[INFO] 4 out of 4 files converted successfully.
[INFO]
[INFO] --- alexandria-maven-plugin:0.1.2:sync (alexandria) @ alexandria-demo ---
[INFO] images.md is already up to date (checksum: 1751689934, last updated: 2018-08-22T02:27:51.789Z)
[INFO] Update document at empahsis.md https://jive.com/docs/DOC-1140809-empahsismd
[INFO] Update document at codeblocks.md https://jive.com/docs/DOC-1140806-codeblocksmd
[INFO] Created new document at https://jive.com/docs/DOC-1140819
[INFO] Synced 4 out of 4 documents with remote https://jive.com/api/core/v3
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2.118 s
[INFO] Finished at: 2018-08-21T23:02:07-04:00
[INFO] ------------------------------------------------------------------------
Requirements
- maven 3.5.2 or greater (for running alexandria-maven-plugin only)
- Java 8
Getting Started
- Check out the javadocs
- After you've ignored that, run
mvn alexandria:indexorjava -jar alexandria-cli.jar indexto generate a config file (.alexandria by default) - add remote url, username, password and update metadata index if necessary (username and password can be set to an envrionment/system variable like
${env.foo}) - run
mvn deployorjava -jar alexandria-cli.jar
See alexandria-demo for a working example of the maven plugin.
<plugin>
<groupId>com.github.macgregor</groupId>
<artifactId>alexandria-maven-plugin</artifactId>
<version>0.1.4</version>
<executions>
<execution>
<id>alexandria</id>
<goals>
<goal>index</goal>
<goal>convert</goal>
<goal>sync</goal>
</goals>
</execution>
</executions>
</plugin>
Concepts
Remotes
Remotes are hosting platforms to upload convertedPath files to. This will almost always be a rest interface for interacting with the platform's api. Remotes included with the release include:
- NoOp Remote - default remote that can be used to run Alexandria without actually uploading to a remote, which can be useful for testing.
- Jive Remote - uses the Jive rest api to upload documents to a Jive document platform.
The remote used is set and configured in the Alexandria config file.
remote:
baseUrl: "https:/jive.com/api/core/v3"
username: "macgregor"
password: "password"
class: "com.github.macgregor.alexandria.remotes.jive.JiveRemote"
New remotes can be added by implementing the Remote interface which defines methods that will be called to create, update or delete a document with the remote.
Alexandria Lifecycle: index -> convert -> sync
Each of these phases can be run independently and reran without any issue. Both mvn deploy and java -jar alexandria-cli.jar will run all three in order. In general errors are collected as they occur and thrown in a batch at the end of a lifecycle phase so that a problem in 1 file wont interfere with others that are fine.
Index
Alexandria generates and stores metadata about your documents. The indexing phase finds documents and adds them to the index file for later use. You can also create or modify this index by hand, for example if the document already exists on the remote you may want to specify the remoteUri so the file is updated and not recreated.
Convert
The convert phase uses the existing metadata index to convert files from markdown to html using flexmark to do the heavy lifting. If your remote supports native markdown, you can set supportsNativeMarkdown and the conversion phase will be skipped and sync will upload the source markdown file.
Sync
This is where most of the complexity is.
- create - if no
remoteUriis set in the metadata, create the deocument - update - if
remoteUriis set in the metadata and the runtimesourceChecksumof the file is different than the storedsourceChecksum(orsourceChecksumis not set), update the document - delete - if a file exists in the index but cannot be found on the local file system, it is considered to be deleted and removed from the remote.
Quirks
- Line breaks can be frustratingly hard to get exactly how you want Putting one or even two newlines between a paragraph doesnt give you a nice space between paragraphs like it does on github. If you really need that white space add a
<p/>\nor<br/>\ntag between paragraphs (the newline is important). - if you are using the alexandria-mojo-plugin on a project that is pom packaging (so just a pom file), you cant you
mvn deployas there is nothing to deploy. You will have to run the goals explicitly:mvn alexandria:index alexandria:clean alexandria:sync. This is a maven thing.
Trobleshooting
- crazy long error about eclipse loggers when trying to install alexandria-maven-plugin. Upgrade maven to at least 3.5.2
- trace level maven logging:
mvn alexandria:sync -Dorg.slf4j.simpleLogger.defaultLogLevel=trace