Switch to Hugo

[XhmikosR]

OK... this is probably something we might never get to do it due to the amount of changes.

That being said, Hugo is blazingly fast, has no dependency like Jekyll has to Ruby, and is very extensible too.

If anyone starts working on it, please let me know.

[Johann-S]

Without dependency 😲 love it 👍

[mdo]

has no dependency

You know the way straight to my heart 😻

[zebapy]

I've wanted to ask about using something like Gatsbyjs as an alternative or is that a crazier ask than Hugo? At least it'd be just node dependency instead of using brew to install Hugo. I'd work on something like that.

[XhmikosR]

Personally, I'd like to skip using React, Preact et all. Thus my choice is to look into Hugo; no extra client side dependencies, no dependencies to run either.

I started working on the Hugo switch, it won't be an easy task, but we'll see how it goes.

https://github.com/twbs/bootstrap/tree/v4-dev-xmr-hugo

@digitalcraftsman: if you have any suggestions please don't hesitate to try the branch and provide any patches to help move forward with this. :)

So far I face the following issues:

1. We need to have Hugo copy the dist dir without us moving it into the static folder; I made an issue in Hugo discourse and I think I'll ask for such a feature in the GitHub repo
2. I can't seem to be able to make shortcodes or highlight to work in index.html; https://discourse.gohugo.io/t/migrating-bootstrap-docs-to-hugo/8898/12?u=xhmikosr
3. I'll need to convert the Jekyll plugins to Hugo shortcodes, but that's after I have something working locally first :P

[digitalcraftsman]

Hello together,

first of all it's great to see projects of this size using Hugo. I'll try to help you as good as I can to speed up your transition.

We need to have Hugo copy the dist dir without us moving it into the static folder; I made an issue in Hugo discourse and I think I'll ask for such a feature in the GitHub repo

The best solution, that was already mentioned in the forum thread, is the ability to specify multiple static dirs. But this is currently not possible. Alternatively, we could make dist the new static directory via the staticDir config option.

The dist directory would remain untouched while other assets from the static folder could be moved into dist. Are the any naming conflicts or other issues that aren't on my radar?

I can't seem to be able to make shortcodes or highlight to work in index.html;

Have a look at my answer in the forum thread. The shown approach works for smaller code examples but it doesn't really scale.

Hopefully I or some other community members will come up with a better solution.

I'll need to convert the Jekyll plugins to Hugo shortcodes, but that's after I have something working locally first :P

I have not much experience with Jekyll so please help me to clarify the different terminologies. Are Jekyll's plugins == Hugo's short codes?

[XhmikosR]

Hi, @digitalcraftsman, thanks for the reply!

The best solution, that was already mentioned in the forum thread, is the ability to specify multiple static dirs. But this is currently not possible. Alternatively, we could make dist the new static directory via the staticDir config option.

The dist directory would remain untouched while other assets from the static folder could be moved into dist. Are the any naming conflicts or other issues that aren't on my radar?

That is indeed a valid workaround. It's just that traditionally the dist folder just contained only our dist files and nothing else. I think I will just combine nodemon which we already have.

Have a look at my answer in the forum thread. The shown approach works for smaller code examples but it doesn't really scale.

Hopefully I or some other community members will come up with a better solution.

Wouldn't it work if I had a partial with that section and in the partial use highlight? Or one can't use shortcodes in index.html at all?

I have not much experience with Jekyll so please help me to clarify the different terminologies. Are Jekyll's plugins == Hugo's short codes?

Not exactly, but Hugo's way of doing things is shortcodes :) Judging by our existent Jekyll plugins, it seems we need the following:

1. bugify.rb: just sets the bug URL based on a first parameter. I shouldn't have trouble converting this
2. callout.rb: just wraps the inner "shortcode" text into <div class="bd-callout bd-callout-#{@type}">#{output}</div>" so it shouldn't be hard either
3. example.rb: similar to callout, it's a wrapper for highlight, so I shouldn't have a problem either
4. markdown-block.rb: this allows us to write markdown code inside HTML code.

So as you can see, it's doable, I just need to have a working directory structure first and I'll get to it.

[XhmikosR]

After spending a few more hours on this, I believe it's a deal breaker the fact that we can't use variables in Markdown. And shortcodes is just not the answer to everything. For example:

Looking to quickly add Bootstrap to your project? Use the Bootstrap CDN, provided for free by the folks at MaxCDN.
Using a package manager or need to download the source files?
[Head to the downloads page.]({{ site.baseurl }}/docs/{{ site.docs_version }}/getting-started/download/)

or

{% highlight html %}
<script src="{{ site.cdn.jquery }}" integrity="{{ site.cdn.jquery_hash }}" crossorigin="anonymous"></script>
<script src="{{ site.cdn.popper }}" integrity="{{ site.cdn.popper_hash }}" crossorigin="anonymous"></script>
<script src="{{ site.cdn.js }}" integrity="{{ site.cdn.js_hash }}" crossorigin="anonymous"></script>
{% endhighlight %}

I was willing to spend any time needed to make the switch happen, but this is just not flexible enough.

So, at this point I consider the Hugo switch as a no go unfortunately, regardless of how much I wanted this to happen. :/

[bep]

Why aren't shortcodes a viable option for both cases above?

[XhmikosR]

Because the above are 2 examples; the docs have hundreds of such cases. And Hugo doesn't throw or anything just silently ignores variables in markdown making things harder to spot...

[bep]

And Hugo doesn't throw or anything just silently ignores variables in markdown making things harder to spot...

If you had asked me, which you did not, I would have said that ...

Why don't you create a param shortcode (or something) which fetches a given variable by name and, if not found, exits with -1 and prints "ERROR: Variable "foo" in page "/path/to/page.md" does not exist". Which would be pretty great error handling. Oh, and not only can shortcodes have great error handling, they can also be both inline and used as blocks, they can be nested as you please ...

But you didn't, and if you want to have that "half empty" attitude looking for blockers, that is fine. I thought having Bootstrap run its documentation site on Hugo would be cool for Hugo, and wanted to chime in with some support. But that support voucher requires a slightly different approach to have any longevity. I have edited enough big Hugo docs sites to be pretty certain that it would have been worth it. I'd even be willing to throw away some functionality to get there.

But up to you.

[XhmikosR]

@bep: Hey, no need to be defensive here (or even aggressive for that matter).

If you look at my messages above you will see that I created the issue and I expressed how much I want to make the switch. Personally, I don't have anything against either Jekyll nor Hugo; I use both of them, and I even prefer to use Hugo in new projects.

That put aside, the issues I face here are not issues that I only face. Having to edit so many markdown files is one thing, having to replace all instances of any custom variables in these files is just insane, at least to me. Searching for {{ in my branch, I get (1147 hits in 90 files).

So, you see why I say that this problem is a deal-breaker, unfortunately.

Oh, and yes, you can expect your end-users to do all these things you mention above, that is fine, I have done it in other personal projects too. But unfortunately, this isn't user-friendly, at all.

Now, I don't know the technical details behind this choice; I'm pretty sure there is some reasoning apart from the usual "content is content and is not supposed to have this". That being said, I'd be glad to have a look again. Either if we get some help (my branch is here) or if/when things become easier for the end-user.