More goodies

More markdown support

The Julia Markdown parser in Julia's stdlib is not exactly complete and Franklin strives to bring useful extensions that are either defined in standard specs such as Common Mark or that just seem like useful extensions.

• indirect references for instance [like so]

or also for images

![][some image]

some people find that useful as it allows referring multiple times to the same link for instance.

• un-qualified code blocks and indented code blocks are allowed and are julia by default

  a = 1 b = a+1

or

a = 1
b = a+1

you can specify the default language with @def lang = "julia". If you actually want a "plain" code block, qualify it as plaintext like

so this is plain-text stuff.

A bit more highlighting

Extension of highlighting for pkg an shell mode in Julia:

(v1.4) pkg> add Franklin
shell> blah
julia> 1+1
(Sandbox) pkg> resolve

you can tune the colouring in the CSS etc via the following classes:

• .hljs-meta (for julia>)

• .hljs-metas (for shell>)

• .hljs-metap (for ...pkg>)

More customisation

Franklin, by design, gives you a lot of flexibility to define how you want stuff be done, this includes doing your own parsing/processing and your own HTML generation using Julia code.

In order to do this, you can define two types of functions in a utils.jl file which will complement your config.md file:

• hfun_* allow you to plug custom-generated HTML somewhere

• lx_* allow you to do custom parsing of markdown and generation of HTML

The former (hfun_*) is most likely to be useful.

Custom "hfun"

If you define a function hfun_bar in the utils.jl then you have access to a new template function {{bar ...}}. The parameters are passed as a list of strings, for instance variable names but it could just be strings as well.

For instance:

function hfun_bar(vname)
  val = Meta.parse(vname[1])
  return round(sqrt(val), digits=2)
end

.hf {background-color:black;color:white;font-weight:bold;}

Can be called with {{bar 4}}: 2.0.

Usually you will want to pass variable name (either local or global) and collect their value via one of locvar, globvar or pagevar depending on your use case. Let's have another toy example:

function hfun_m1fill(vname)
  var = vname[1]
  return pagevar("menu1", var)
end

Which you can use like this {{m1fill title}}: Home. Of course in this specific case you could also have used {{fill title menu1}}: Code blocks2.

Of course these examples are not very useful, in practice you might want to use it to generate actual HTML in a specific way using Julia code. For instance you can use it to customise how tag pages look like.

A nice example of what you can do is in the SymbolicUtils.jl manual where they use a hfun_ to generate HTML encapsulating the content of code docstrings, in a way doing something similar to what Documenter does. See how they defined it.

Note: the output will not be reprocessed by Franklin, if you want to generate markdown which should be processed by Franklin, then use return fd2html(markdown, internal=true) at the end.

Custom "lx"

These commands will look the same as latex commands but what they do with their content is now entirely controlled by your code. You can use this to do your own parsing of specific chunks of your content if you so desire.

The definition of lx_* commands must look like this:

function lx_baz(com, _)
  # keep this first line
  brace_content = Franklin.content(com.braces[1]) # input string
  # do whatever you want here
  return uppercase(brace_content)
end

You can call the above with \baz{some string}: SOME STRING.

Note: the output will be reprocessed by Franklin, if you want to avoid this, then escape the output by using return "~~~" * s * "~~~" and it will be plugged in as is in the HTML.