writefreely / hugo-importer Goto Github PK

The project should include a suite of unit tests that ensure everything's working as expected.

Tests should be included for the following files:

• utilities.go
• parser.go
• logger.go

Feature Overview

When a command-line flag (--images) is set, the hugo-importer tool should upload local images to Snap.as and update image links in the source content.

Constraints

This feature is only available to Write.as Pro subscribers. At a minimum, if the --instance flag is set, the tool should return an error.

There are two main ways to include an image in the source content, and the tool should handle both:

1. Using Markdown (!["Alt text here"](/link/to/image.jpeg))
2. Using HTML (<img src="/link/to/image.jpeg" alt="Alt text here" />)

Implementation

If the --images flag is set, the tool shall do the following when parsing a source file:

1. Search the content of the file for an image (either Markdown or HTML)
2. Determine if the image is local or remote (more on this below)
3. If image is remote, continue searching; otherwise
4. Confirm the image exists in the filesystem at /static/link/to/image.jpeg
5. Upload the image to Snap.as and get the new URL
6. Replace the original image source URL with the Snap.as URL
7. Continue searching the source file for more images

Image Source: Absolute vs Relative Paths

Related to step 2 in the implementation details above, a local image's source may be represented via an absolute path (https://example.com/link/to/image.jpeg), or a relative path (/link/to/image.jpeg). In the latter case, it's clear that the image is local; in the former, however, the tool must determine if the base URL (in this scenario, example.com) is the URL of the Hugo site being migrated. Fortunately, the baseURL parameter in the Hugo site configuration file lets us make this comparison.

This project requires, at a minimum, the following documentation:

• Read Me
• License
• Contribution Guidelines
• Code of Conduct

Hugo provides built-in shortcodes that "represent very common usage" for convenience. The intention is to keep Markdown clean, but because they are proprietary to Hugo, they don't migrate nicely, so a Tweet shortcode ends up looking like:

{{< tweet 877500564405444608 >}}

Where possible, these would make more sense as plain URLs:

https://twitter.com/twitter/status/877500564405444608

For a subset (e.g. gist, tweet, and youtube), converting shortcodes to URLs allows Pro users to get proper embeds via embed.as; in all cases, special care must be taken to craft a valid URL from the shortcode, so we'll limit ourselves to the following shortcodes:

This doesn't cover all built-in shortcodes, nor does it cover all options for the shortcodes listed above, but I believe it's a pretty solid set of shortcodes to cover for launch. We can include a note in the README about this limitation, and extend it if the demand exists.