Laika wiki

evergreen documentation


Hi again Jens.

I studied some but did not yet use for an application. An application idea I'd like is some form of dynamic resume.

https://planet42.github.io/Laika/03-preparing-content/03-theme-settings.html#the-helium-theme

Here you mention of the possibility to use Bootstrap based themes: do you have any example of this kind, please?

Theme Settings
planet42.github.io • 14 min read
Jens Halm sent the following message at 11:11 AM

View Jens’ profile
Jens Halm  11:11 AM
Hey Nick, I am not sure I understand your question: the documentation you refer to explicitly talks about *not* using Bootstrap in Laika's built-in theme to keep it more lightweight. So I'm not sure what the question is about. Do you want to know how to use Bootstrap with Laika? If so, why do you think you need it? It's certainly possible, but would create much more work for you as you cannot easily use the default theme then.
Nick Vintila sent the following message at 11:28 AM


Nick Vintila  11:28 AM
Hi Jens,

Indeed am thinking that having a theme using Bootstrap may come closer to what am thinking about this "dynamic resume".
Jens Halm sent the following message at 11:53 AM

Sorry, that's still a bit too vague for giving you more concrete pointers. Personally I am not a huge fan of Bootstrap for a whole range of reasons, but I suspect that's not the kind of discussion you want to have. :-)

I could provide more feedback if you'd have a concrete example of functionality that you need and that the default theme does not give you. If you want to bypass the Helium theme, you can check chapters like "Creating Templates" in the docs that allow you to do most of the things "from scratch".(Edited)
Nick Vintila sent the following messages at 11:55 AM

Ah, am not hung up with Boostrap. :-)
I am trying to think how to combine more advanced HTML/CSS templates with Laika. 
Is that making sense?
Jens Halm sent the following message at 12:03 PM

Roughly. :-) It depends on the level of customization you need. Laika has a completely seamless opt-in/opt-out approach about the default theme. From "off-the-shelf" to "fully customized" you can have anything in-between, roughly in this kind of order:

1) Use Helium with all default settings.
2) Adjust Helium config in Scala, only customizing colors or font families and sizes and a few other things.
3) Keep using Helium, but add/override custom CSS (you can simply place additional CSS files anywhere into the input directories).
4) Do 3), but also override the default template if you also need to adjust the HTML output, see chapters "Creating Templates" and "Overriding Renderers" for controlling HTML output.
5) Skip Helium entirely by installing "Theme.empty" and write all HTML/CSS by hand
6) When you want to re-use what you did in 5), turn it into your own theme as described in the chapter "Creating Themes"

Laika is that flexible and on purpose, as it's also meant to be used as a "toolkit for creating toolkits" and not just for end users.
Nick Vintila sent the following messages at 12:04 PM

Yes, I read about all of that.
And am getting the abstractions to enough extent to like them.
But the practical application would be helped by an example for 5+. :-)

I remember looking at Jekyll with these "eyes" and was getting a bit lost between the semantics of the template language and the semantics of CSS theme (hence "bootstrap").
Jens Halm sent the following message at 12:08 PM

The "Creating Templates" chapter does not give you enough info to get started? I currently do not include some hello world project for that scenario as I somehow felt it would be quite obvious. But apparently that's not the case.
Nick Vintila sent the following messages at 12:09 PM

Ah, very likely I did not ... apply myself enough.

In the context of the discussion above about "ref" and directives: what would it take to turn all mentions of hashtags from *text* to links? Say mentions to `#Spark` in the body of the resume.

I'd need to parse the text and manually produce the links, right?
Does not have to be hash tags - just some way to mark managed keywords.
Jens Halm sent the following message at 12:15 PM

Why not use Markdown syntax for that? It's just one character more. :-) e.g. [Spark]. And then define all the links just once globally with https://planet42.github.io/Laika/03-preparing-content/02-navigation.html#global-link-definitions

Navigation
planet42.github.io • 9 min read
Nick Vintila sent the following messages at 12:15 PM

>  define all the links just once globally

aahhhh! missed that

Will study but: does this work across multiple pages?
like a wiki?
Jens Halm sent the following message at 12:17 PM

I wouldn't call it "global" otherwise :-)
Remove reaction
:blush:
1

Nick Vintila sent the following messages at 12:18 PM

Hmm... nice.
Thant's sorely missing from markdown.
Likely because it does not have abstractions for mapping between concepts and nested files on disk.
Okay. ... will study. And hope to run into a example :-)

quick thought: would you agree to publish such that the latest site keeps these urls (also) work?

https://planet42.github.io/Laika/03-preparing-content/02-navigation.html
Now this works
https://planet42.github.io/Laika/0.17/03-preparing-content/02-navigation.html

Thanks!
Jens Halm sent the following message at 11:34 AM

Hm, you mean some kind of /latest/ in the path? Generally useful, but a bit complicated as it is a static site, not a web app, so it would need to render twice. Thinking of adding it as a config option.
Remove reaction
:+1:
1

Nick Vintila sent the following message at 11:35 AM

Yes. 
Maybe just create a soft link at web server level? (hack)
Jens Halm sent the following message at 11:35 AM

Hm, can you do that with github pages?
Nick Vintila sent the following messages at 11:35 AM

Ah... dunno.
https://github.com/chetabahana/symlink

chetabahana/symlink
github.com • 1 min read
"Symbolic links work with GitHub Pages!"
Not critical but I harvest pages to Evernote and then links break. :-)
Same thing with hypothes.is highlights.
Jens Halm sent the following messages at 11:37 AM

Well, the breakage will never happen again, it's just now when going from unversioned to versioned
In the future those links will still work, the version chooser dropdown will just include newer versions
And I might add a config option for displaying a warning on pages for EOL versions
Nick Vintila sent the following messages at 11:39 AM

Okay. Still, even with incremental changes in text hypothes.is will continue to work well unless dramatic changes happened.
Anyway, just a perspective.
Jens Halm sent the following message at 11:41 AM

Yes, there are really two approaches, and I'm not sure which one most users would expect. And both are definitely doable. When I start to promote it again (after the next release - 0.18) I hope I get more user feedback and features will be more driven by that then.
Remove reaction
:+1:
1

Nick Vintila sent the following messages at 11:42 AM

Okay, Thanks. Do not meant to take your focus with that.
But do mean to do it with this one: https://twitter.com/semanticbeeng/status/1322929673366573057?s=20

I would really be grateful for a close consideration.
When you can afford it ...
Basically mdoc make publishing of books with Scala code really nice : coming from Scala code to markdown.
And laika handles the publishing ... well.... you know. :-)
My insight is that combining both would reign supreme over all other tools that publish code centered documentation.
Jens Halm sent the following message at 11:46 AM

I'm not familiar with the current status of mdoc, the way I see it being used in the Scala community is that they currently configure it for a two-step process: 1st pass is just compiling Scala and producing *new* markdown with the results inserted and then running whatever tool you want to generate the site.
Nick Vintila sent the following message at 11:47 AM

Sounds right to me ...
Jens Halm sent the following messages at 11:47 AM

So it's already integrated, but somewhat loosely
It just breaks 2 of Laika's design choices when combined: Laika does not require you to use it as an sbt plugin, and Laika does not mandate Markdown. So right now, these two traits get lost when you combine Laika with mdoc.
Post-0.18 I might have time to look at whether they can be more closely integrated, avoiding the two-step process.
But 0.18 is first about adding a dev server and I definitely want that first. :-)
Nick Vintila sent the following message at 11:49 AM

Laika is not specific to publishing code so sbt is not required, ofc - right?
Jens Halm sent the following message at 11:51 AM

Yes, but also the general design is decoupled on purpose. Most other sbt plugins bury functionality within their plugin code so it's hard to use outside that context. Laika is *mostly* a library and the sbt plugin is only a wrapper around the library, making up just 2% of the code base.
Nick Vintila sent the following messages at 11:51 AM

I would not think to compromise Laika's design.
But maybe we can have another tool to combine.
More like an application of laika then a design change.
Jens Halm sent the following messages at 11:55 AM

I can't provide much deeper insight right now, but after 0.18 I want to look into how mdoc is actually implemented, and then I know more about how to combine it with Laika. So most likely somewhat after Christmas. :-)
Remove reaction
:+1:
1

Would you mind to create a github issue for your suggestion to re-publish as `latest` or `current`? Makes it more likely I look into it. :-)
Nick Vintila sent the following message at 11:56 AM

Sure, cannot ask for a change in focus.
Was only trying to validate that the use case makes sense.
Jens Halm sent the following messages at 11:57 AM

it's not a change in focus, a ticket is not a demand to add the featuere *now*. :-) Tickets can remain open for a while until I get around to working on them,
it's a perfectly valid user request otherwise :-)
Nick Vintila sent the following messages at 11:58 AM

Oki, will create it.
If you concur this use case does interest you then I will create and issue for this too.
Oki, thanks.
This idea is documented here https://github.com/vsch/idea-multimarkdown/issues/650

Will refer it from the new laika issue.
Thanks for now!

As custom language injection working with concepts from wiki · Issue #650 · vsch/idea-multimarkdown
github.com • 2 min read
Jens Halm sent the following message at 12:06 PM

View Jens’ profile
Jens Halm  12:06 PM
I think I don't understand the screenshot, what exactly is the user attempting to do there?
Nick Vintila sent the following messages at 12:10 PM

The gist of the need is for publishing. The part with the editor is to (ideally) have IDE support. But not the main point in a Laika context.
My main need is this wiki like support to maintain knowledge.
If you have the time to look at the code links it may make more sense what I mean by "wiki".
Jens Halm sent the following message at 12:12 PM

which code links?
Nick Vintila sent the following message at 12:17 PM

In here https://github.com/SemanticBeeng/fpinscalabe/tree/master/guide/src/test/scala/org/specs2/guide

SemanticBeeng/fpinscalabe
github.com • 1 min read
Jens Halm sent the following message at 12:18 PM

oh, you want to swap from code in md to md in code?
Nick Vintila sent the following message at 12:19 PM

https://github.com/SemanticBeeng/fpinscalabe/blob/ed32d31cc573b79d8fd8366f26f6a2693c7260a8/guide/src/test/scala/org/specs2/thirdparty/blogs/cakesolutions/Existential_types_in_Scala.scala#L26

SemanticBeeng/fpinscalabe
github.com • 1 min read
Jens Halm sent the following messages at 12:20 PM

that's what I meant
Laika would be completely out of the picture then, the tooling is kind of always the host language (e.g. Scala in this case), so Laika cannot really help with this. The Scala IDE plugin and compiler would be needed to help with that.
Nick Vintila sent the following messages at 12:22 PM

Not focused on the plugin part.
Just the interlinking through code / concept references like laika does it with references you explained to me above.
Jens Halm sent the following message at 12:24 PM

Well, when the above example is in an md file and not in Scala code then you can use Laika to process those links, but you can do this with today's version, so I'm not sure where the question is then :-)
Nick Vintila sent the following messages at 12:26 PM

" not in Scala code" - it *is* scala code
I imagine a separate processor to turn such code in "data" for Laika
Jens Halm sent the following message at 12:28 PM

Well, it is a string with markdown... if you think about a tool that processes Scala code and "collects" the md from some properties, yes, you can do that, too, but it's pretty much beyond the scope of what Laika Core would do, so part of the 3rd-party library, which I'm happy to help with as adviser, but not as coder. :-)
Nick Vintila sent the following message at 12:30 PM

Yes, sure, it would be a separate tool than laika.
Indeed am looking just for use case validation and maybe some design consulting (if it gets to that).
Jens Halm sent the following message at 12:34 PM

The Laika-specific part would be easy, I think. You just have to construct the inputs manually instead of just pointing at a directory, see http://planet42.github.io/Laika/0.17/02-running-laika/02-library-api.html#freely-composing-inputs.

Library API
planet42.github.io • 1 min read
Nick Vintila sent the following message at 12:34 PM

Yes, something like that.
Jens Halm sent the following messages at 12:35 PM

Not sure if you read those parts, but MD input in Laika is always simply mapped to a logical path. It *can* come from the filesystem, but it does not have to, it can be strings with a logical path assigned to it.
The rendering then *could* be physical instead, turning the virtual paths from the inputs into file paths relative to the output directory you write to.
Nick Vintila sent the following message at 12:36 PM

Yes, I can follow to some superficial level.
Jens Halm sent the following message at 12:37 PM

I don't understand your full requirements, but my gut feeling is you would have more work with the code independent from Laika then with the Laika-specific part, which would be fairly simply, maybe just a single class.
Nick Vintila sent the following messages at 12:37 PM

Yes, understood.
That would be one level of integration.
Another integration with mdoc, at the level of developer workflow, would require some mind meld with the mdoc author.
If I understand well they work with one MD at a time.
Where Laika is a multi page publishing system.
It is at this level that I meant the tweet above.
mdoc is more well known so integration may be a good use case for laika imho.
laika is far too cool and very undiscovered and such a use case may bring attention. :-)
Jens Halm sent the following message at 12:42 PM

But for mdoc I don't see how Laika with mdoc would help your use case. Both tools are pretty far from it.
Nick Vintila sent the following messages at 12:43 PM

Let us say they are too separate issues.
But the integration between the two may create the basis for my application because it would bring the practice of markdown and Scala code generation and full scale/multi-page publishing together.
It would make "evergreen documentation" more practical for developers and publishers.
Then I would add my wiki likeinterlinking.
Jens Halm sent the following message at 12:45 PM

I don't understand where you see mdoc in this picture, what would it do in your scenario?
Nick Vintila sent the following message at 12:45 PM

mix type checked executable code into publishing.
Jens Halm sent the following message at 12:47 PM

It's a bit too abstract, I'm not following, if you'd have a concrete example of full input and full output, even if it's just made up and not based on a tool, I might understand better.
Nick Vintila sent the following messages at 12:48 PM

Hmmm... here's an example of using mdoc 
https://github.com/fd4s/fs2-kafka/blob/master/docs/src/main/mdoc/producers.md

All that code compiles are runs but also generates MD.

fd4s/fs2-kafka
github.com • 1 min read
But it is single page, not full site/book like Laika.
Jens Halm sent the following message at 12:49 PM

yes, but your code links are the other way round: md embedded in Scala, not Scala embedded in md, I don't see the connection.
Nick Vintila sent the following messages at 12:50 PM

Ah, that is just how it "works" in this current impl based on specs2.
I am open to other ways to do the interlinking.
But the interlinking is secondary to multi-page publishing that laika brings.
Jens Halm sent the following message at 12:51 PM

But if you are fine with simple md files with scala code embedded, what would you miss? I'd think that mdoc and Laika together would give you that today
Nick Vintila sent the following message at 12:52 PM

Interlinking: maybe I could use special types that when referenced in code would be processed to create something similar to the global links in laika.
Jens Halm sent the following message at 12:53 PM

You mean the class names used in code are linked to pages somewhere?
Nick Vintila sent the following messages at 12:53 PM

Hmm... when I reference concept.catamorphism then there is no tool to generate a link to an existing MD page for that. (mulling)
The wiki idea is to mix concept definitions with code that uses them.
Jens Halm sent the following message at 12:54 PM

But would the links be within the code blocks or outside?
Nick Vintila sent the following messages at 12:55 PM

Basically the business use case is that everybody keeps writing books and blog posts but there is no way to converge the knowledge....
(trying to answer) The concepts would be defined outside code ...
And their uses in various code examples would accrue meaning.
Jens Halm sent the following message at 12:56 PM

it's clear on the abstract level, I don;t understand the details about what you are missing,, e.g. But would the links be within the code blocks or outside?
Nick Vintila sent the following message at 12:56 PM

Are you familiar with distributional semantics as used in modern NLP ? :-)
Jens Halm sent the following message at 12:56 PM

Can you please answer this one question first?
Nick Vintila sent the following message at 12:57 PM

References / links would be in many other pages speaking this language...
Jens Halm sent the following message at 12:57 PM

yes, but *within* the code sample blocks or around?
Nick Vintila sent the following message at 12:57 PM

Thinking ... Both?
Jens Halm sent the following message at 12:59 PM

I'm asking this specific question, because this is the only thing the combination of Laika and mdoc cannot do today, as Laika does not process link syntax in code blocks. For linking outside (in normal paragraphs, lists, etc. it would just work). I might be wrong, but I feel you underestimate what Laika and mdoc together would give you today, meaning I don't see how any special integration would be required.
Nick Vintila sent the following message at 1:00 PM

> underestimate what Laika and mdoc together would give you today

So once that mix is done then interlinking in one sense would be out of the box?
Jens Halm sent the following messages at 1:02 PM

Yes, because mdoc does not do the linking, it would be Laika in the 2nd phase. mdoc has Docusaurus intgegration, but that is optional, you can skip it and use Laika for the processing. So *all* that mdoc would do is compile the Scala.
The flow is MD with source -> mdoc -> MD with compiled output -> Laika -> HTML
Nick Vintila sent the following message at 1:03 PM

Oki cool. Nice to see you have thought of this part
Jens Halm sent the following messages at 1:03 PM

I haven't :-)
You can do this with any tool.
Laika in the 2nd step does not even need to be aware of the fact that its MD inputs had been pre-processed.
Nick Vintila sent the following messages at 1:04 PM

Oki, But what if I have more MD in Laika...
How would the interlinking of MD from mdoc and MD from Laika see eachother?
Jens Halm sent the following message at 1:06 PM

You don't need this distinction
Nick Vintila sent the following message at 1:06 PM

Very likely I am not knowledgeable enough in either.
But mdoc is single page and laika is multi-page and if I need to interlink...
Jens Halm sent the following messages at 1:06 PM

You can point mdoc to any inputs, if some of them don't have any Scala code it will just not touch them
mdoc does not link at all
and it does not need to, it writes back MD with all your link syntax untouched
Nick Vintila sent the following message at 1:07 PM

So the mdoc generated MD would be hard referenced from laika - right?
Jens Halm sent the following messages at 1:08 PM

You have three directories: 1) raw input 2) mdoc output 3) laika output - all files would move from 1 to 2 to 3, when they move from 1 to 2 no linking happens
so Laika sees only the inputs from 2), it does not deal with or touch those from 1), it inter-links everything in 2) and that's all you need.
Nick Vintila sent the following message at 1:11 PM

> when they move from 1 to 2 no linking happens

That already sounds like an issue because as author I want to write them interlinked because
1. they reference shared concepts
2. some code pieces are shared
3. chapters of a series of blog posts

(just thinking out loud) and I'd like to ensure the linking checks out.
Jens Halm sent the following messages at 1:12 PM

the linking happens from 2 to 3
you don;t need it from 1 to 2, you never do anything with the output from 2, it's just an interim directory in your file system
I think you have some misconception about either mdoc or Laika that makes you suspect some limitation that does not exist.
Nick Vintila sent the following messages at 1:13 PM

Your paradigm might work. Just need to think it hands on.
Quite possible.
Jens Halm sent the following messages at 1:14 PM

it's what everyone else does in the Scala community, just not with Laika...
but the workflow is the exactly the same, they also use doc-tools that cross-link between docs
so it's not something novel I just made up, it's what literally most of Scala Open Source libs do with their docs.
Nick Vintila sent the following messages at 1:16 PM

Well, in a wiki paradigm I reference the concept. Do not need to know the hard path to a doc.
The wiki knows to abstract over the location of the document for the concept and creates proper web links.
Jens Halm sent the following message at 1:17 PM

sure, but that's just the extra-bit where Laika offers you more options, but the workflow is the same
Nick Vintila sent the following message at 1:17 PM

At mdoc level am missing this and if need to cross link I'd need to hard code links to files.
Jens Halm sent the following messages at 1:18 PM

Laika allows you to reference any way you want, but that does not change the workflow others are using, it only changes the syntax you write in.
Again, you don't need any linking capabilities from mdoc, I think it actually does not even have any.
Nick Vintila sent the following message at 1:18 PM

Oki but if laika is not involved in first step then cannot benefit from this "extra bit", no?
Jens Halm sent the following message at 1:18 PM

why not?
Nick Vintila sent the following message at 1:19 PM

Oki, I hear you and will need to think hands-on.
Jens Halm sent the following message at 1:19 PM

I'm sorry, but I'm somehow not understanding what you don't understand. :-)
Nick Vintila sent the following message at 1:20 PM

I understand but partially. :-)
Jens Halm sent the following messages at 1:20 PM

so I need to stress it one more time: whether mdoc is capable of processing links or not is completely irrelevant to you!
if that is not clear to you, you are somehow on the wrong track
Nick Vintila sent the following messages at 1:22 PM

Example: writing a blog post in mdoc and want to reference concept.catamorphism using markdown syntax, But that concept is documented in a book written in laika.
How does mdoc know to generate the link ?
Jens Halm sent the following message at 1:23 PM

why do you want mdoc to generate links at all? that's already the wrong track
Nick Vintila sent the following message at 1:23 PM

I only want mdoc to reference [concepts.catamorphism] - no hardcoded links to docs
Jens Halm sent the following message at 1:24 PM

But mdoc predominantly processes code blocks, not links.
Nick Vintila sent the following messages at 1:24 PM

Well, first of all I need to ensure that concept exists when I write the page
Well that is kind of my problem.
I want the code and the words around it to speak the language of the business domain.
Jens Halm sent the following message at 1:24 PM

no I don;t think it is
Nick Vintila sent the following messages at 1:25 PM

And to "prove: that using concepts that conpile
... in the sense that they exist and can be found during compilation of all doc
Jens Halm sent the following messages at 1:25 PM

I think you somehow struggle to grasp how it is a 2-step process and mdoc does not have to do anything in the 1st step other than ONLY compile your code
missing links can be reported by Laika in step 2
Nick Vintila sent the following message at 1:26 PM

So can I write [concepts.catamorphism] in my mdoc page ?
Jens Halm sent the following messages at 1:28 PM

View Jens’ profile
Jens Halm  1:28 PM
I haven't used it yet myself, but I would assume that it either does not validate links or has a flag to disable validation. If not it's maybe a change I would request. But again this is the standard workflow for others: skipping all features for mdoc and then use a 2nd tool for the full MD processing.
I would want it to ignore those links
Nick Vintila sent the following messages at 1:29 PM

Oki so we have some unknowns to "think hands on" - that was my point :-)
But it is not a link : only a markup to be resolved somehow.
By laika? Sure, I just need to think it hands on. :-)
Not disregarding your overall workflow - just cannot see at this level (my ignorance likely).
I just do not want maintain hardcoded links.
In laika I can define them globally once.
Jens Halm sent the following messages at 1:32 PM

View Jens’ profile
Jens Halm  1:32 PM
yes, and mdoc does not force you to (unless it has really unexpected behaviour)
https://scalameta.org/mdoc/docs/modifiers.html

JVM Modifiers · mdoc
scalameta.org • 9 min read
look at their docs, they show examples that go from MD to MD, with ONLY the code blocks changed.
Nick Vintila sent the following messages at 1:33 PM

> show examples that go from MD to MD

Okay, did not see those yet.
But modifiers are for code blocks, not concepts.
And markdown traditionally wants user to hardcode links.
Jens Halm sent the following message at 1:34 PM

View Jens’ profile
Jens Halm  1:34 PM
but that's critical bit: mdocs OUTPUT is MD, it ONLY deals with scala code
Nick Vintila sent the following messages at 1:34 PM

Hence my thoughts to use laika for that.
mdoc source is MD as well
Jens Halm sent the following messages at 1:35 PM

View Jens’ profile
Jens Halm  1:35 PM
yes, but you keep talking about limitations that don't exist.
it's simply not mdocs job to process your links
Nick Vintila sent the following messages at 1:36 PM

I declared that I need to think it hands on because am likely missing enough understanding.

But if you insist then I am going to ask again what I do not see

If I change https://github.com/fd4s/fs2-kafka/blob/master/docs/src/main/mdoc/producers.md to add 
[concepts.catamorphism] (not a link) then how can I have the final MD point to a full path defined by laika.

fd4s/fs2-kafka
github.com • 1 min read
Jens Halm sent the following message at 1:37 PM


I feel you major misconception is simply around the fact that mdoc is MD->MD NOT MD->HTML
Nick Vintila sent the following messages at 1:37 PM


... for that concept
Ah, I see.
So I kind of have a point with a closer integration :-)
Jens Halm sent the following message at 1:39 PM

I explained that like 7 times, but maybe my wording is not clear. :-)
Nick Vintila sent the following messages at 1:39 PM

To leave to HTML for last
In this discussion I tried to stay close to my requirements and did not attempt to hypothesize about design.
And this initial design does not meet the requirements.
That is okay, A closer integration could solve it. :-)
Jens Halm sent the following messages at 1:41 PM


There is no need to closer integration, mdoc does not need to know about Laika and Laika does not need to know about mdoc
it's simple configuration: configure mdocs output to be Laika's input
Nick Vintila sent the following messages at 1:41 PM


I understand what you are saying.
Will do that.

Did not expect to keep you so long.
I value very much and do not want to use all the favor. :-)