You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@community.apache.org by sebb <se...@gmail.com> on 2023/03/26 15:12:27 UTC

comdev-website: why are files named __index.md rather than _index.md?

Most of the index files are named __index.md, except for one which is _index.md.

Why is this?

Do they serve a different purpose?

Sebb

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org

Re: comdev-website: why are files named __index.md rather than _index.md?

Posted by Roy Lenferink <rl...@apache.org>.
Thanks for asking this and pointing out the empty pages Sebb!

The __index.md was a suggested workaround on the Hugo forums (can't find
an exact reference).

This workaround was needed because the community.apache.org website used a
combination of different URLs, e.g.:

/about/
/committers/
/committers/voting.html
/newcommitter.html
/newbiefaq.html

By default having the example file structure below, Hugo will generate
a directory for every file, e.g.:

source/about/_index.md => target/content/about/index.html
source/about/some-page.md => target/content/about/some-page/index.html
source/some-page.md => target/content/some-page/index.html

Because comdev uses a combination of different URLs and I didn't
want to break existing URLs, we use an option called uglyURLs [1].

This allows for e.g.:

source/about.md => target/content/about.html
source/some-page.md => target/content/some-page.html

To still allow a top level file (e.g. /about/index.html) I created the
__index.md files (double underscore), because this was suggested as
a workaround for above /some-page.html and /some-page/ URLs.

I just noticed that Hugo supports the 'url' part in Markdown files now [2],
which IIRC wasn't an option with the Hugo release we were using before
(or I missed the existence of that option). This seems to better fit for
what we want and also won't generate the empty pages listed by Sebb.

I have gone ahead and updated the __index.md to the Hugo advertised
_index.md [3] and use the 'url' option [4]

I hope this explains it a bit, if additional details are needed let me know
and
I'll try my best to write them down :-)

[1]
https://github.com/apache/comdev-site/blob/ae48404766416af1bbd0d72d3cdc8f323d5d293e/hugo.toml#L9
[2] https://gohugo.io/content-management/urls/
[3] https://gohugo.io/content-management/organization/#index-pages-_indexmd
[4]
https://github.com/apache/comdev-site/commit/ae48404766416af1bbd0d72d3cdc8f323d5d293e

Op di 28 mrt 2023 om 01:01 schreef sebb <se...@gmail.com>:

> Just noticed that there are quite a few redundant files in the generated
> site:
>
> https://community.apache.org/about.html
> https://community.apache.org/calendars.html
> https://community.apache.org/committers.html
> https://community.apache.org/contributors.html
> https://community.apache.org/gsoc.html
> https://community.apache.org/mentoring.html
> https://community.apache.org/newcomers.html
> https://community.apache.org/newsletter.html
> https://community.apache.org/speakers.html
>
> i.e. all the top-level html files apart from
> https://community.apache.org/index.html
>
> These spurious entries correspond with the __index.md files
>
> There are also a few pages which are not linked into the site
> navigation, e.g. the pages under history
>
> Also one or two broken breadcrumbs, e.g.
> 'Apache way' on the page
> https://community.apache.org/apache-way/apache-project-maturity-model.html
>
>
> On Mon, 27 Mar 2023 at 15:33, <rb...@rcbowen.com> wrote:
> >
> > On Sun, 2023-03-26 at 16:12 +0100, sebb wrote:
> > > Most of the index files are named __index.md, except for one which is
> > > _index.md.
> > >
> > > Why is this?
> > >
> > > Do they serve a different purpose?
> >
> > Yeah, I wondered this, too, but just stick with the convention. I'd
> > like to understand this. Roy, can you give some insight here please?
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
> > For additional commands, e-mail: dev-help@community.apache.org
> >
>

Re: comdev-website: why are files named __index.md rather than _index.md?

Posted by sebb <se...@gmail.com>.
Just noticed that there are quite a few redundant files in the generated site:

https://community.apache.org/about.html
https://community.apache.org/calendars.html
https://community.apache.org/committers.html
https://community.apache.org/contributors.html
https://community.apache.org/gsoc.html
https://community.apache.org/mentoring.html
https://community.apache.org/newcomers.html
https://community.apache.org/newsletter.html
https://community.apache.org/speakers.html

i.e. all the top-level html files apart from
https://community.apache.org/index.html

These spurious entries correspond with the __index.md files

There are also a few pages which are not linked into the site
navigation, e.g. the pages under history

Also one or two broken breadcrumbs, e.g.
'Apache way' on the page
https://community.apache.org/apache-way/apache-project-maturity-model.html


On Mon, 27 Mar 2023 at 15:33, <rb...@rcbowen.com> wrote:
>
> On Sun, 2023-03-26 at 16:12 +0100, sebb wrote:
> > Most of the index files are named __index.md, except for one which is
> > _index.md.
> >
> > Why is this?
> >
> > Do they serve a different purpose?
>
> Yeah, I wondered this, too, but just stick with the convention. I'd
> like to understand this. Roy, can you give some insight here please?
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
> For additional commands, e-mail: dev-help@community.apache.org
>

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org

Re: comdev-website: why are files named __index.md rather than _index.md?

Posted by rb...@rcbowen.com.
On Sun, 2023-03-26 at 16:12 +0100, sebb wrote:
> Most of the index files are named __index.md, except for one which is
> _index.md.
> 
> Why is this?
> 
> Do they serve a different purpose?

Yeah, I wondered this, too, but just stick with the convention. I'd
like to understand this. Roy, can you give some insight here please?

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@community.apache.org
For additional commands, e-mail: dev-help@community.apache.org