Uploaded image for project: 'Sling'
  1. Sling
  2. SLING-6955

Convert Sling website to JBake and gitpubsub

    Details

    • Type: Bug
    • Status: Open
    • Priority: Major
    • Resolution: Unresolved
    • Affects Version/s: None
    • Fix Version/s: None
    • Component/s: Site
    • Labels:
      None

      Description

      I've started experimenting with JBake to generate the Sling website. If that works well we might switch to that + gitpubsub to have a more flexible way to generate the site.

      My current experiment is at https://github.com/bdelacretaz/sling-jbake, at this point the site starts looking like the current one and many pages work well.

      Internal links will need to be converted, all *.md files need a more complete "front matter" section, currently I have a stub for that, and I think images need to move under the assets folder.

      To play with that, generate the site with the bake.sh script (setup shamelessly copied from https://github.com/apache/incubator-tamaya-site)

        Activity

        Hide
        bdelacretaz Bertrand Delacretaz added a comment -

        Contributions are welcome of course, for now I'm aiming to recreate the website without any layout changes, to be able to validate the conversion.

        Show
        bdelacretaz Bertrand Delacretaz added a comment - Contributions are welcome of course, for now I'm aiming to recreate the website without any layout changes, to be able to validate the conversion.
        Hide
        bdelacretaz Bertrand Delacretaz added a comment -

        The site looks pretty good now but there's a number of "small" things to fix, I have added a TODO list in the README.

        Show
        bdelacretaz Bertrand Delacretaz added a comment - The site looks pretty good now but there's a number of "small" things to fix, I have added a TODO list in the README.
        Hide
        rombert Robert Munteanu added a comment -

        Being able to build the website locally for various tests would be great. Also, moving it to git would be an interesting first step in our git transition.

        Show
        rombert Robert Munteanu added a comment - Being able to build the website locally for various tests would be great. Also, moving it to git would be an interesting first step in our git transition.
        Hide
        kwin Konrad Windszus added a comment -

        Could someone list here quickly the drawbacks of the Apache CMS (https://www.apache.org/dev/cms.html)? Currently I am not clearly seeing what problems we try to solve with the new website. Let me start the list here with things I see

        1. Local builds are hard to achieve
        2. Based in SVN instead of Git
        3. It seems that the Apache CMS is basically no longer maintained/developed

        But migrating the website again seems quite some effort, given the fact that even the last migration is not 100% finished yet...

        Show
        kwin Konrad Windszus added a comment - Could someone list here quickly the drawbacks of the Apache CMS ( https://www.apache.org/dev/cms.html)? Currently I am not clearly seeing what problems we try to solve with the new website. Let me start the list here with things I see Local builds are hard to achieve Based in SVN instead of Git It seems that the Apache CMS is basically no longer maintained/developed But migrating the website again seems quite some effort, given the fact that even the last migration is not 100% finished yet...
        Hide
        rombert Robert Munteanu added a comment -

        Those seem to be the drawbacks that I see. The first 2 are also factors in discouraging external contributors. If we move to a more standard stack it should be simpler for casual contributors.

        Show
        rombert Robert Munteanu added a comment - Those seem to be the drawbacks that I see. The first 2 are also factors in discouraging external contributors. If we move to a more standard stack it should be simpler for casual contributors.
        Hide
        bdelacretaz Bertrand Delacretaz added a comment -

        Konrad Windszus I agree with your list. I think making local builds + staging easier is a big plus, and the fact that the Apache CMS development stopped is a major problem going forward.

        ...even the last migration is not 100% finished yet...

        Do you see concrete points which we wouldn't be able to solve with JBake? I agree that a new migration will probably bring a few new differences with existing content, and that's not ideal, but breaking things earlier than later (i.e. when the Apache CMS is eventually retired) is probably better.

        I have categorized the TODOs at https://github.com/bdelacretaz/sling-jbake and it doesn't look dramatic.

        I'm traveling these days and this is a good project to work on in the intervals, so I'm hoping to make more progress in the next few days.

        Show
        bdelacretaz Bertrand Delacretaz added a comment - Konrad Windszus I agree with your list. I think making local builds + staging easier is a big plus, and the fact that the Apache CMS development stopped is a major problem going forward. ...even the last migration is not 100% finished yet... Do you see concrete points which we wouldn't be able to solve with JBake? I agree that a new migration will probably bring a few new differences with existing content, and that's not ideal, but breaking things earlier than later (i.e. when the Apache CMS is eventually retired) is probably better. I have categorized the TODOs at https://github.com/bdelacretaz/sling-jbake and it doesn't look dramatic. I'm traveling these days and this is a good project to work on in the intervals, so I'm hoping to make more progress in the next few days.
        Hide
        kwin Konrad Windszus added a comment -

        Is there anywhere an official statement from Apache about the CMS no longer being maintained? Is there a replacement recommendation from Apache INFRA maybe?

        Show
        kwin Konrad Windszus added a comment - Is there anywhere an official statement from Apache about the CMS no longer being maintained? Is there a replacement recommendation from Apache INFRA maybe?
        Show
        rombert Robert Munteanu added a comment - The closest that I found was https://issues.apache.org/jira/browse/INFRA-13644?focusedCommentId=16035309&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-16035309
        Hide
        bdelacretaz Bertrand Delacretaz added a comment -

        Is there anywhere an official statement from Apache about the CMS no longer being maintained?

        I don't have references right now but the Apache CMS being deprecated and not maintained anymore has been mentioned several times by our infra team, including the example that Robert mentions

        Is there a replacement recommendation from Apache INFRA maybe?

        The recommendation is to use whatever we want to generate the website, and gitpubsub to sync the generated pages, which matches this effort.

        Show
        bdelacretaz Bertrand Delacretaz added a comment - Is there anywhere an official statement from Apache about the CMS no longer being maintained? I don't have references right now but the Apache CMS being deprecated and not maintained anymore has been mentioned several times by our infra team, including the example that Robert mentions Is there a replacement recommendation from Apache INFRA maybe? The recommendation is to use whatever we want to generate the website, and gitpubsub to sync the generated pages, which matches this effort.
        Hide
        bdelacretaz Bertrand Delacretaz added a comment -

        Note that JBake is moving from the pegdown Markdown parser to flexmark-java, probably in the next version, see https://github.com/jbake-org/jbake/pull/376 and https://github.com/vsch/flexmark-java

        Show
        bdelacretaz Bertrand Delacretaz added a comment - Note that JBake is moving from the pegdown Markdown parser to flexmark-java, probably in the next version, see https://github.com/jbake-org/jbake/pull/376 and https://github.com/vsch/flexmark-java
        Hide
        bdelacretaz Bertrand Delacretaz added a comment -

        I have moved the repository to https://git-wip-us.apache.org/repos/asf?p=sling-site.git and asked for a temporary live setup to test the results before switching, INFRA-14390

        Show
        bdelacretaz Bertrand Delacretaz added a comment - I have moved the repository to https://git-wip-us.apache.org/repos/asf?p=sling-site.git and asked for a temporary live setup to test the results before switching, INFRA-14390
        Hide
        rombert Robert Munteanu added a comment -

        My notes after some quick tests:

        Show
        rombert Robert Munteanu added a comment - My notes after some quick tests: tables still seem to be broken, see http://localhost:8820/documentation/development/slingstart.html code formatting does not work properly, see http://localhost:8820/documentation/development/slingstart.html HTML output as-is ( maybe due to code formatting not working ) , see http://localhost:8820/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html warning icon not visible , see http://localhost:8820/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html favicon is the jetty one not the sling one. Maybe due to the local Jetty server?
        Hide
        bdelacretaz Bertrand Delacretaz added a comment -

        Thanks for testing!

        Commits 825c0f9 and f1fa804 fixed the problematic tables - a single minus sign in a cell causes them to break, I have replaced that with a minus sign in brackets as a workaround (those entries mean "no default value").

        Preformatted text and code was broken by a previous mass modification, I have reverted that, should be ok now.

        I think http://localhost:8820/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html is also ok as a result.

        All the icons were missing, should be fixed by commit 081c292

        Favicon should be fixed by commit 08947a4

        Can you cross-check? And feel free to dig deeper for other issues which are not in the README todo list

        Show
        bdelacretaz Bertrand Delacretaz added a comment - Thanks for testing! Commits 825c0f9 and f1fa804 fixed the problematic tables - a single minus sign in a cell causes them to break, I have replaced that with a minus sign in brackets as a workaround (those entries mean "no default value"). Preformatted text and code was broken by a previous mass modification, I have reverted that, should be ok now. I think http://localhost:8820/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html is also ok as a result. All the icons were missing, should be fixed by commit 081c292 Favicon should be fixed by commit 08947a4 Can you cross-check? And feel free to dig deeper for other issues which are not in the README todo list
        Hide
        bdelacretaz Bertrand Delacretaz added a comment -

        There are still a few pages with broken tables, I have listed them in the README, will fix them later.

        Show
        bdelacretaz Bertrand Delacretaz added a comment - There are still a few pages with broken tables, I have listed them in the README, will fix them later.
        Hide
        rombert Robert Munteanu added a comment -

        Thanks, it's starting to look good Some more notes besides what is listed in the README

        A minor thing, but I think it would be good to get code highlighting back. It makes both java and HTML code much easier to read.

        Show
        rombert Robert Munteanu added a comment - Thanks, it's starting to look good Some more notes besides what is listed in the README breadcrumbs are missing ; contrast http://localhost:8820/project-information/project-team.html with http://sling.apache.org/documentation/the-sling-engine.html . the sidebar design differs quite a bit. I think the old one was better. We don't have to keep it but I think we should improve what we have before going live the preformat area does not have any padding ( fixed with 6931ba4fedd014824ecb643c31fede0b4e8826d9 ) A minor thing, but I think it would be good to get code highlighting back. It makes both java and HTML code much easier to read.

          People

          • Assignee:
            bdelacretaz Bertrand Delacretaz
            Reporter:
            bdelacretaz Bertrand Delacretaz
          • Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

            Dates

            • Created:
              Updated:

              Development