hakyll-shortcut-links: Use shortcut-links in markdown file for Hakyll

[ hakyll, library, markdown, mpl, web ] [ Propose Tags ]

Use shortcut-links in markdown file for Hakyll. See README for more details.


[Skip to Readme]
Versions [faq] 0.0.0.0, 0.1.0.0
Change log CHANGELOG.md
Dependencies base (>=4.13.0.0 && <4.14), hakyll (==4.13.*), mtl (>=2.2.2 && <2.3), pandoc-types (==1.20.*), parsec (>=3.1.14 && <3.2), shortcut-links (>=0.5.0.0 && <0.6), text (==1.2.*) [details]
License MPL-2.0
Copyright 2019-2020 Kowainik
Author Veronika Romashkina, Dmitrii Kovanikov
Maintainer Kowainik <xrom.xkov@gmail.com>
Category Web, Hakyll, Markdown
Home page https://github.com/kowainik/hakyll-shortcut-links
Bug tracker https://github.com/kowainik/hakyll-shortcut-links/issues
Source repo head: git clone https://github.com/kowainik/hakyll-shortcut-links.git
Uploaded by vrom911 at 2020-02-29T17:40:17Z
Distributions NixOS:0.1.0.0
Downloads 475 total (40 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs uploaded by user
Build status unknown [no reports yet]

Modules

[Index] [Quick Jump]

Downloads

Maintainer's Corner

For package maintainers and hackage trustees


Readme for hakyll-shortcut-links-0.1.0.0

[back to package description]

hakyll-shortcut-links

scissors GitHub CI Hackage MPL-2.0 license

This library adds the support of the shortcut-links library in the static website generator library — Hakyll.

That being said, it means that you can use shortcuts from shortcut-links library or custom ones in your markdown files which would be extended into complete URLs during the Hakyll site compilation process.

Here is the example of how links could look like before expansion:

Here is going to be a link to the [hakyll-shortcut-links](@hackage) library on Hackage.
And another link to the [GitHub sources](@github(kowainik):hakyll-shortcut-links).

which is going to be transformed into the ordinary links automatically by the library functions:

Here is going to be a link to the [hakyll-shortcut-links](http://hackage.haskell.org/package/hakyll-shortcut-links) library on Hackage.
And another link to the [GitHub sources](https://github.com/kowainik/hakyll-shortcut-links).

For the full list of the supported shortcuts, you can check ShortcutLinks.All module of the shortcut-links library.

How to use in a Hakyll project

To use hakyll-shortcut-links in your ready Hakyll project, you would need to go through the following steps:

Add the dependency

Add hakyll-shortcut-links under the build-depends section in your .cabal file. If you use Stack build tool, you would need to add the library into extra-deps list in the stack.yaml file.

Change a standard pandocCompiler

Here we assume that you already have a Hakyll project. If not then you can use these tutorials to create one. Anyway, you would eventually have the code that uses pandocCompiler that could look like this function:

compile $
    pandocCompiler >>= loadAndApplyTemplate "templates/post.html" postCtx

All you need to change is to use allShortcutLinksCompiler or shortcutLinksCompiler function from this library instead of the standard pandocCompiler:

import Hakyll.ShortcutLinks (allShortcutLinksCompiler)

...

compile $
    allShortcutLinksCompiler >>= loadAndApplyTemplate "templates/post.html" postCtx

That's all!

There could be another situation. You could already have some custom Compiler function:

-- | A pandoc compiler which makes all entries of "42" bold automatically.
bold42Compiler :: Compiler (Item String)
bold42Compiler = pandocCompilerWithTransform
    myHakyllReaderOptions
    myHakyllWriterOptions
    make42Bold

In this case, you can use the applyAllShortcuts function directly. All you need is to combine two transformations:

myCompiler :: Compiler (Item String)
myCompiler = pandocCompilerWithTransformM
    myHakyllReaderOptions
    myHakyllWriterOptions
    (applyAllShortcuts . make42Bold)

Use shortcuts in your docs

The hardest part is done, now you can create links using the shortcuts, and the Hakyll is going to build full URLs for them. Happy coding!

Example

Here is an example of the pull request that introduces the hakyll-shortcut-links library into the scope:

As you can see by the diff the only actual change needed for that was replacing pandocCompiler with allShortcutLinksCompiler.

Examples of the @github shortcut:

  • Link to a user :

    | Shortcut | Plain markdown | | ------------------------------------ | ------------------------------------ | | [foo](@github) | [foo](https://github.com/foo) | | [foo Github profile](@github(foo)) | [foo Github profile](https://github.com/foo) |

  • Link to a repository :

    | Shortcut | Plain markdown | | ----------------------------------- | --------------------------------------------- | | [bar](@github:foo) | [bar](https://github.com/foo/bar) | | [Github Source](@github(foo):bar) | [Github Source](https://github.com/foo/bar) |

Acknowledgement

Icons made by Freepik from www.flaticon.com is licensed by CC 3.0 BY.