devonfw/devonfw-guide

Improvements for Website (filenames, URLs, namespacing)

Closed this issue · 11 comments

hohwille commented

As discussed in MS teams, I would like to discuss the following ideas for improvement:

  • Consider omitting AsciiDoc extension in the generated HTML filenames of the https://devonfw.com website. Currently we have file extensions .asciidoc.html. Instead it would be better to have just .html if easily possible.
  • Consider renaming all submodule-folders to just the stack/product name omitting the obsolete .wiki suffix
  • Consider using a namespace for each stack/product in the URL of the website/pages to avoid name clashing. Currently two stacks/products could overwrite their content when they use an include with the same filename. See https://devonfw.com/website/pages/docs/master-doc.asciidoc_layers.html
  • Consider shortening the filenames of the stack/product documentations. E.g. omitt master- prefix. If namespace above can be done, even use index.html/index.asciidoc as entry point for every stack/product.

ATTENTION: We only want to address quickwins. I can also assist to some degree. However, if we would make things overcomplicated and would have to add an HTML post-processing or so we can drop any of the above ideas.

hohwille commented

From @maybeec:

Agree to take up low-hanging-fruits, but as far as I was involved in the solution finding, the script we are currenlty using is highly bound to the asciidoc internals and producing a more or less static output without any configuration options. So as you proposed chaning structures, we would need to dig into https://github.com/owenh000/asciidoctor-multipage an possibly adapt it
owenh000/asciidoctor-multipageA multipage HTML converter for Asciidoctor.

hohwille commented

Motivation:

We should on the long run consider the following aspects:

  • stable URLs for bookmarks, etc. (at least for the toplevel aspects such as the stacks)
  • short and rememberable URLs - yes there are people using autocompletion in address-bar of the browser to open specific pages (or to find back their tab in a mess of hundreds of tabs)!

Therefore IMHO the URLs and "filenames" matter.

hohwille commented

Feedback from @jambulud

  1. https://devonfw.com/website/pages/docs/master-devon4j.asciidoc.html to https://devonfw.com/website/pages/docs/devon4j.html:
    It is possible to an extent, you could rename master-whatever.asciidoc to whatever.asciidoc and the url obtained would be .../docs/devon4j.asciidoc.html but ".asciidoc" won't be removed.
    To remove ".asciidoc" we have to modify the html spliter because we don't have control over how the filenames are generated.

  2. Also I could change the internal structure such that: https://devonfw.com/website/pages/docs/master-doc.asciidoc_layers.html would become https://devonfw.com/website/pages/docs/guide-layers.html
    Continuing with the previous point, filenames are generated automatically: The html splitter takes a bunch of .asciidoc files, then divides it's content in less files whose names are referenced by the Table Of Contents (sidebar).
    If we modify filenames and folders afterwards, then TOC has to be updated
    Changing .../master-doc.asciidoc_layers.html to .../guide-layers.html would not be possible because:

  • master-doc.asciidoc_layers.html does not have an exact equivalent in .asciidoc, it is not exactly the transformation of guide-layers.asciidoc
  • the merge and split process previously mentioned makes master-doc.asciidoc_layers.html contain guide-layers.html and more files.
  • In general, multiple .asciidoc files ends in one .html file and all .html files in the same folder
  • If you want to use submodule-folders in the url then .html files should be moved to folders named like the submodules and the TOC updated

  1. Remove .wiki suffix
    I think there is no problem with this, but I would need to check if ".wiki" is being used somewhere ( like "if( variable == '.wiki') then ..." )

  2. No you dont as you can see here: https://devonfw.com/website/pages/docs/master-doc.asciidoc_layers.html no devon4j added in URL hence no namespacing via submodule folder
    Usually master files are included like:

// master.asciidoc
include::devon4ng.wiki/master-devon4ng.asciidoc[...]
// master-devon4ng.asciidoc
include::file1.asciidoc[...]
include::file2.asciidoc[...]
include::filen.asciidoc[...]

But for the specifyc case of devon4j is beig done like:

// master.asciidoc
include::devon4nj.wiki/master-devon4j.asciidoc[...]
// master-devon4j.asciidoc
include::master-doc.asciidoc[...]    --> Notice this extra level

and

// master-doc.asciidoc
include::file1.asciidoc[...]
include::file2.asciidoc[...]
include::filen.asciidoc[...]

Currently I don't know the exact fix for this beside removing the extra level

Comment from Jörg H. on this:
See devonfw/devon4j#160 for the reason.

hohwille commented

OK. First of all it seems more tricky than I thought it would be.
To prevent clushes and overwriting of files, I will change documentation of devon4j such that for each toplevel chapter I create a separate .asciidoc file with all the includes required. As long as we can not guarantee a namespacing per module with our toolchain, I will name those devon4j-«chapter».asciidoc. A little drawback is that architecture needs to be renamed and it might be referenced from many other places. I do not really like that our website is taking part of our freedom to name and structure our asciidoc files.

The module folders can be renamed easily but as long as we can not use them for the namespacing inside the URL, there is no huge benefit in doing this though it might still be a little nice to have improvement.

The renaming of master-«name».asciidoc to «name».asciidoc makes sense to me and can be done easily. As it affects two repos it means we temporary have to break the site for a short while as we have to do changes in devonfw-guide as well as in the stack/tool repo.

maybeec commented

sry, but I did not get it entirely.
Acutally, as far as I know, there is namespacing, isn't it @jambulud ?
Otherwise, why is there "master-ide.assidoc" in front of all urls:
https://devonfw.com/website/pages/docs/master-ide.asciidoc_integrated-development-environment.html

maybeec commented

it's not nice, but it serves the solution for conflict resolution across git submodules

jambulud commented

sry, but I did not get it entirely.
Acutally, as far as I know, there is namespacing, isn't it @jambulud ?
Otherwise, why is there "master-ide.assidoc" in front of all urls:
https://devonfw.com/website/pages/docs/master-ide.asciidoc_integrated-development-environment.html

the master-ide comes from the master-file's name, if you call your master-devon4j to my-master-java and you include it from master.asciidoc, your url will be https://../docs/my-master-java.asciidoc_integrated...

hohwille commented

I follow a convention to enure some kind of namespacing and avoid name-clashing:

  • For the product/stack, I use the name as prefix for all toplevel asciidoc files (e.g. devon4j or devonfw-ide)
  • The main entry point for the website is just this prefix with .asciidoc suffix (e.g. devon4j.asciidoc). This will replace the master-«name».asciidoc (I will provide a PR for this guide repo with the updates).
  • All further includes that are reflected by the website (those containing main-level chapters) all use that suffix as well (e.g. devon4j-guides.asciidoc or devon4j-layers.asciidoc or devonfw-ide-usage.asciidoc). This will prevent the potential clashing and give as reasonable URLs and allows better bookmarking of chapters from the website.
  • I will also include the renaming of the submodules (removing .wiki suffix) into my PR for the repos/submodules of my stack as a nice to have improvement and hope other stacks will follow.
hohwille commented

It works almost...

hohwille commented

I now understood that the submodules actually point to the wiki git so the .wiki suffix still makes sense. So if I understood it correctly it works as following:

  • documentation folder content is updated in a repository
  • via travis these changes are automatically synced to corresponding wiki of the same repositoriy.
  • the wiki git is what is included in the devonfw-guide as a submodule

Still I did not understand where and when these submodules are updated, but after all the structure now makes sense to me.

hohwille commented

For devonfw-ide now all is resolved and works as expected.
For devon4j the first two links currently do not work properly as the seem not to hold the chapter declaration:

I try to fix this but have to think how I can do that without duplicating chapters with sub-sections...
Further, I will do a final cleanup and delete the master-*.asciidoc files.
However, I already consider this issue as done.