Alexandria

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

1. Check out the javadocs
2. After you've ignored that, run mvn alexandria:index or java -jar alexandria-cli.jar index to generate a config file (.alexandria by default)
3. 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})
4. run mvn deploy or java -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 remoteUri is set in the metadata, create the deocument
• update - if remoteUri is set in the metadata and the runtime sourceChecksum of the file is different than the stored sourceChecksum (or sourceChecksum is 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/>\n or <br/>\n tag 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 deploy as 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

Links

• Javadocs
• Travis Build
• Code Climate
• Coveralls
• Maven Artifacts