~adnano/kiln-discuss

6 3

Seeking feedback for kiln 0.2.0

Details
Message ID
<CAW4V8HEESR9.1VI2KEZP6K2UW@nitro>
DKIM signature
pass
Download raw message
I plan on releasing kiln 0.2.0 soon. Version 0.2.0 brings a lot of
changes and improvements.

The major change is that kiln can now build sites of any content format.
Sites can now specify multiple build tasks, where each tasks reads files
from the content directory, optionally processes them with external
commands, passes them through templates, and then writes the output to
the output directory. This means that, in theory, kiln can be used to
build Gemini sites, export Gemini sites to HTML with the gmnitohtml [1]
command, or even render Markdown sites to HTML [2]. This makes kiln more
flexible than other static site generators like Hugo, which allow custom
output formats but not custom input formats. The cost of this
flexibility is that kiln no longer has built-in functionality for
rendering Gemini text to HTML, and must rely on external commands to do
so.

[1]: https://sr.ht/~adnano/gmnitohtml It preserves all the functionality
of the kiln Gemini text to HTML renderer, with the added bonus that it
will soon be able to be configured with command-line arguments.

[2]: This requires the use of an external command to render Markdown to
HTML.

Titles are no longer parsed from Gemini content, as kiln no longer cares
about the content format. Instead, titles and dates can be specified in
frontmatter. Dates are still parsed from page filenames, though I wonder
if we should rid of that functionality and opt for specifying all
metadata in frontmatter. Let me know if you would prefer to specify
dates in filenames. Frontmatter will also unlock more configurability,
such as the ability to specify how pages in a directory are sorted (they
are currently sorted by date).

The name of the input directory has been changed from "src" to
"content". kiln now also has support for a static content directory for
storing static assets which will be copied to the output directory
as-is.

The 'kiln new' command will generate an empty Gemini site along with the
default templates to make it easy to get started.

You can try the latest changes by building kiln from source. Feedback is
appreciated.
Maria Górniakowska
Details
Message ID
<64719ab3-688c-d8ad-f6bc-f1ddacc4d37d@wp.pl>
In-Reply-To
<CAW4V8HEESR9.1VI2KEZP6K2UW@nitro> (view parent)
DKIM signature
pass
Download raw message
Nice work.

I have to minor suggestions:

*  doc/kiln.1.scd lines 225, 226 input format should be html, output html

* Links to articles in subdirectories are generated as absolute paths 
"/subdirectory/"
     I think better solution is to use relative path "subdirectory/
     Suggested change: file page.go line 64 remove first "/" in page.Path


Thank you for all the effort.
Details
Message ID
<CAXZKCNHNBY2.3EALB3YGF04G5@nitro>
In-Reply-To
<64719ab3-688c-d8ad-f6bc-f1ddacc4d37d@wp.pl> (view parent)
DKIM signature
pass
Download raw message
On Mon Apr 26, 2021 at 5:39 PM EDT, Maria Górniakowska wrote:
> I have to minor suggestions:
>
> * doc/kiln.1.scd lines 225, 226 input format should be html, output html

I pushed a fix for this. Thanks for letting me know.

> * Links to articles in subdirectories are generated as absolute paths
> "/subdirectory/"
> I think better solution is to use relative path "subdirectory/
> Suggested change: file page.go line 64 remove first "/" in page.Path

The problem is that this will only work for files in the root directory
and will generate invalid links for files in subdirectories. Though I
can see the value of generating relative links. Perhaps we can allow
specifying a custom base URL for the site like Hugo does? Or perhaps a
function can be implemented which returns the path relative to the
current path, and then templates can be modified to use relative paths.
Maria Górniakowska
Details
Message ID
<95e70db4-9447-1876-7fa8-29a79ff46dce@wp.pl>
In-Reply-To
<64719ab3-688c-d8ad-f6bc-f1ddacc4d37d@wp.pl> (view parent)
DKIM signature
pass
Download raw message
Right, I didn't think about subdirectories. In my opinion allowing 
custom base URL
is perfectly fine solution. Although I not sure which solution would be 
easier to implement.


> On Mon Apr 26, 2021 at 5:39 PM EDT, Maria Górniakowska wrote:
>> I have to minor suggestions:
>>
>> * doc/kiln.1.scd lines 225, 226 input format should be html, output html
> I pushed a fix for this. Thanks for letting me know.
>
>> * Links to articles in subdirectories are generated as absolute paths
>> "/subdirectory/"
>> I think better solution is to use relative path "subdirectory/
>> Suggested change: file page.go line 64 remove first "/" in page.Path
> The problem is that this will only work for files in the root directory
> and will generate invalid links for files in subdirectories. Though I
> can see the value of generating relative links. Perhaps we can allow
> specifying a custom base URL for the site like Hugo does? Or perhaps a
> function can be implemented which returns the path relative to the
> current path, and then templates can be modified to use relative paths.
Details
Message ID
<20210515191048.2445ef1e@shaka>
In-Reply-To
<CAW4V8HEESR9.1VI2KEZP6K2UW@nitro> (view parent)
DKIM signature
pass
Download raw message
Hi Adnan! Thank you very much for your contribution.

In response to your request, my feedback is as follows:

> [2]: This requires the use of an external command to render Markdown
> to HTML.

I'm not sure I understand this aspect. I have tested kiln + md2gemini[1]
and the latter does not play well with documents that use a
frontmatter, which is a pity. If the option to remove the frontmatter
is omitted, kiln parsing does not work as expected (empty h1 tag). If
you choose to preserve it, md2gemini will result in a file with a long
succession of "-" as a header.

[1]: https://github.com/makeworld-the-better-one/md2gemini

> Dates are still parsed from page filenames, though I wonder
> if we should rid of that functionality and opt for specifying all
> metadata in frontmatter. Let me know if you would prefer to specify
> dates in filenames.

Personally, I like it much more dates in filenames. I believe this is a
widespread practice among static content generators. I don't see why
anyone should have to find themselves in the dilemma of having to
choose between one or the other option. It would be much better to
extract the date from the file name and pass it to the frontmatter, if
this is possible of course.

From my own experience:

I would really love to use kiln as my framework as I see great
potential in it. However, I have not had very good results on my side.
I have followed the development of kiln since official version 0.1.0
and several inconsistencies prevent this from happening.

Before I begin, I would like to share a few facts about my environment:

- Debian Testing i686
- Go v1.16.4 linux/386
- kiln v0.1.0-113-gb20ffe0

My config.toml:

title = "$ cat /dev/random > /dev/null 2>&1"
urls = ["https://ivanruvalcaba.cf", "gemini://ivanruvalcaba.cf"]

[feeds]
"/blog/" = "$ cat /dev/random > /dev/null 2>&1"

[permalinks]
"/blog/" = '/{{ .Date.Format "2006/01/02" }}/{{ path.Base .Path }}/'

# Build the site
[[tasks]]
input = [".gmi"]
output = ".gmi"
template = ".gmi"
output_dir = "public/gemini"

# Export an HTML version of the site
[[tasks]]
input = [".gmi"]
output = ".html"
template = ".gmi"
postprocess = "gmnitohtml -t templates/baseof.html"
static_dir = "static"
output_dir = "public/https"

I will now begin with my approach:

# This will generate a feed which will be written to
public/blog/atom.xml
[feeds]
"/blog/" = "$ cat /dev/random > /dev/null 2>&1"

This specification does not work on my side, both atom.xml files are
generated in the base directory (public/https or public/gemini as the
case may be).

[permalinks]
"/blog/" = '/{{ .Date.Format "2006/01/02" }}/{{ path.Base .Path }}/'

The generation of the public file permalinks is correct, however kiln
creates the empty folder "blog" in both public directories. Something
that in my opinion is unnecessary.

kiln does not automatically include the list of published articles in
my index file. The content of my index.gmi file is as follows:

---
title: $ cat /dev/random > /dev/null 2>&1
---

Hello, world!

## Posts

=> atom.xml Atom feed

Sometimes the generation of the permalink of this file turns out to be
0001/01/01/index.gmi or index.html as the case may be.

Under certain circumstances unknown to me, kiln seems to ignore the
"title" content in the frontmatter resulting in an empty h1 header.

At the moment these are just some inconsistencies that I have
encountered when using kiln in my day to day life. I hope that the
criticism will be taken well.

Finally, I would really like to see some practical examples of usage
and templating (frontmatter + html) included in the README. Since it
seems to me that sometimes the manpage is not so intuitive.

Best regards.
-- 
«Si no puedo seguir el ritmo de todo lo que me vaya llegando, voy a
tratar de mantenerme al día de todo lo que pueda. Si no puedo responder
a todos los mensajes que deseo responder, responderé únicamente
algunos, a medida que me vayan llegando.»

Fingerprint: 026D B8BE 3F5C 1533 FF9D 4CC2 DBB4 A5B9 17E5 72DE
Details
Message ID
<CBE9LEI5VXDY.25X6ILJU82GB@nitro>
In-Reply-To
<20210515191048.2445ef1e@shaka> (view parent)
DKIM signature
pass
Download raw message
Thanks for the feedback!

On Sat May 15, 2021 at 8:11 PM EDT, Iván Ruvalcaba wrote:
> I'm not sure I understand this aspect. I have tested kiln + md2gemini[1]
> and the latter does not play well with documents that use a
> frontmatter, which is a pity. If the option to remove the frontmatter
> is omitted, kiln parsing does not work as expected (empty h1 tag). If
> you choose to preserve it, md2gemini will result in a file with a long
> succession of "-" as a header.
>
> [1]: https://github.com/makeworld-the-better-one/md2gemini

I think that another tool (perhaps mdtohtml) will need to be developed
for converting markdown to HTML. That said, the md2gemini command should
work with kiln as a preprocess command. In your task configuration, you
could write something along the lines of:

	[[tasks]]
	input = [".gmi", ".md"]
	output = [".gmi"]
	template = ".gmi"
	preprocess.md = "md2gemini"
	output_dir = "public/gemini"

> Personally, I like it much more dates in filenames. I believe this is a
> widespread practice among static content generators. I don't see why
> anyone should have to find themselves in the dilemma of having to
> choose between one or the other option. It would be much better to
> extract the date from the file name and pass it to the frontmatter, if
> this is possible of course.

I've decided to keep this functionality intact.

> This specification does not work on my side, both atom.xml files are
> generated in the base directory (public/https or public/gemini as the
> case may be).

This was a bug and has been fixed.

> [permalinks]
> "/blog/" = '/{{ .Date.Format "2006/01/02" }}/{{ path.Base .Path }}/'
>
> The generation of the public file permalinks is correct, however kiln
> creates the empty folder "blog" in both public directories. Something
> that in my opinion is unnecessary.

This has now been fixed, though if an Atom template is configured for
that directory the directory will still be created.

> kiln does not automatically include the list of published articles in
> my index file. The content of my index.gmi file is as follows:

I recently made a change that requires index.gmi files to use the name
'_index.gmi' for the index template to apply. Omitting the leading
underscore will result in the page template being used instead. This is
similar to the behavior of Hugo. That could be the problem here.

> Sometimes the generation of the permalink of this file turns out to be
> 0001/01/01/index.gmi or index.html as the case may be.

This is also likely because the index file is treated as a page instead
of an index file. Using the name '_index.gmi' should resolve the issue.

> Under certain circumstances unknown to me, kiln seems to ignore the
> "title" content in the frontmatter resulting in an empty h1 header.

This is odd. Perhaps it is a result of converting the Gemini text to
HTML? The gmnitohtml tool uses the content of the first top-level
heading line (e.g. '# Hello world') as the title. Are the affected pages
missing a title line? If so, I would suggest either adding the missing
title lines or using HTML templates and rendering the Gemini text to
HTML beforehand with a preprocess command.

> Finally, I would really like to see some practical examples of usage
> and templating (frontmatter + html) included in the README. Since it
> seems to me that sometimes the manpage is not so intuitive.

I agree. The documentation is still a work in progress. I also want to
write a simple tutorial for onboarding new users.
Details
Message ID
<20210516222930.5f4fb32c@shaka>
In-Reply-To
<CBE9LEI5VXDY.25X6ILJU82GB@nitro> (view parent)
DKIM signature
pass
Download raw message
Thank you very much for your response. With the new changes and the
relevant clarifications, finally everything seems to be working
correctly. Nice job!

Best regards.

-- 
«Si no puedo seguir el ritmo de todo lo que me vaya llegando, voy a
tratar de mantenerme al día de todo lo que pueda. Si no puedo responder
a todos los mensajes que deseo responder, responderé únicamente
algunos, a medida que me vayan llegando.»

Fingerprint: 026D B8BE 3F5C 1533 FF9D 4CC2 DBB4 A5B9 17E5 72DE
Reply to thread Export thread (mbox)