hakyll-shortcut-links-0.1.0.2: Use shortcut-links in markdown file for Hakyll
Copyright(c) 2019-2021 Kowainik
LicenseMPL-2.0
MaintainerKowainik <xrom.xkov@gmail.com>
Safe HaskellNone
LanguageHaskell2010

Hakyll.ShortcutLinks

Description

This package allows to use shortcut-links package in websites generated by hakyll.

The flexible interface allows to use the supported huge collection of shortcuts along with using custom ones.

Here is a few examples of the `@github` shortcut:

  • Link to a user:
ShortcutPlain markdown
[foo](@github)[foo](https://github.com/foo)
[foo Github profile](@github(foo))[foo Github profile](https://github.com/foo)
  • Link to a repository:
ShortcutPlain markdown
[bar](@github:foo)[bar](https://github.com/foo/bar)
[Github Source](@github(foo):bar)[Github Source](https://github.com/foo/bar)
Synopsis

Pandoc functions

Functions to transform Pandoc documents. These functions modify markdown links to the extended links.

These are the most generic functions. They work inside the monad m that has MonadError [String] instance. You can use the pure version of these function because there's MonadError instance for Either:

applyShorcuts :: [([Text], Shortcut)] -> Pandoc -> Either [String] Pandoc
applyAllShorcuts :: Pandoc -> Either [String] Pandoc

If you have your own hakyll options for your custom pandoc compiler, you can use this function like this:

pandocCompilerWithTransformM
    myHakyllReaderOptions
    myHakyllWriterOptions
    (applyShortcuts myShortcuts)

applyShortcuts Source #

Arguments

:: forall m. MonadError [String] m 
=> [([Text], Shortcut)]

Shortcuts

-> Pandoc

Pandoc document that possibly contains shortened links

-> m Pandoc

Result pandoc document with shorcuts expanded

Modifies markdown shortcut links to the extended version and returns Pandoc with the complete links instead.

Unlike applyAllShortcuts which uses the hardcoded list of the possible shortcuts (see allShortcuts), the applyShortcuts function uses the given list of custom provided shortcuts. For your help you can use All module to see all available shortcuts.

If you want to add a couple of custom shortcuts to the list of already existing shortcuts you can do it in the following way:

(["hk", "hackage"], hackage) : allShortcuts

applyAllShortcuts :: MonadError [String] m => Pandoc -> m Pandoc Source #

Modifies markdown shortcut links to the extended version and returns Pandoc with the complete links instead.

Similar to applyShortcuts but uses allShortcuts as a list of shortcuts to parse against.

Hakyll functions

Functions to integrate shortcut links to hakyll.

hakyll-shortcut-links provides out-of-the-box Compilers that translate markdown documents with shortcut links into the documents with extended links.

Usually you would want to use this feature on your blog post markdown files. Assuming that you already have similar code for it:

match "blog/*" $ do
    route $ setExtension "html"
    compile $
        pandocCompiler
            >>= loadAndApplyTemplate "templates/post.html" defaultContext
            >>= relativizeUrls

All that you would need to do is to replace pandocCompiler with shortcutLinksCompiler or allShortcutLinksCompiler:

match "blog/*" $ do
    route $ setExtension "html"
    compile $
        allShortcutLinksCompiler
            >>= loadAndApplyTemplate "templates/post.html" defaultContext
            >>= relativizeUrls

shortcutLinksCompiler :: [([Text], Shortcut)] -> Compiler (Item String) Source #

Our own pandoc compiler which parses shortcut links automatically. It takes a custom list of shortcut links to be used in the document.

allShortcutLinksCompiler :: Compiler (Item String) Source #

Our own pandoc compiler which parses shortcut links automatically. Same as shortcutLinksCompiler but passes allShortcuts as an argument.

Shortcut-links reexports

This is the module from shortcut-links library that introduces the functions that by given shortcuts creates the Resulting URL (if possible).

This module stores a large number of supported Shortcuts. It also reexports a useful function allShortcuts that is a list of all shortcuts, together with suggested names for them.

In hakyll-shortcut-links we are exporting both functions that work with the standard list of allShortcuts, but also we provide the option to use your own lists of shortcuts (including self-created ones).

For example, if you want to use just github and hackage shortcuts you can create the following list:

(["github"], github) : (["hackage"], hackage) : []

If you want to create your own shortcut that is not included in ShortcutLinks.All module you can achieve that implementing the following function:

kowainik :: Shortcut
kowainik _ text = pure $ "https://kowainik.github.io/posts/" <> text

myShortcuts :: [([Text], Shortcut)]
myShortcuts = [(["kowainik"], kowainik)]

And it would work like this:

[blog post](@kowainik:2019-02-06-style-guide)

=>

[blog post](https://kowainik.github.io/posts/2019-02-06-style-guide)