Hi all, I have just submitted a PR ( https://github.com/apache/ofbiz-framework/pull/1079) to convert the project's README file from AsciiDoc to Markdown. You can check the result on my fork's branch at https://github.com/golja/ofbiz-framework/tree/convert-readme-to-md
Apart from some minor typo corrections, I faithfully converted the content of the file. In my opinion, there is room for improvement, but for this first commit, I preferred to keep the content as is. Best regards Anahita Il giorno mar 7 apr 2026 alle ore 12:24 Anahita Goljahani < [email protected]> ha scritto: > Hi all, > > I did some tests and found that adding a README.md file to the project’s > root directory is not sufficient to prevent GitHub from displaying the > README located in the ./github directory on the main OFBiz repository page. > What actually solves the problem is renaming the README file in the > ./github directory. I have just submitted a PR (#1071) to rename the file > to README-CI-CD.md > > https://github.com/apache/ofbiz-framework/pull/1071 > > For your information, I have started working on converting the .adoc file > and will submit a PR as soon as it’s done. > > Best regards > Anahita > > > Il giorno mar 7 apr 2026 alle ore 09:22 Jacopo Cappellato < > [email protected]> ha scritto: > >> As a temporary solution, while we work on the conversion, we could create >> a >> README.md file in the root of the project that tells the user to open >> README.adoc: this new file (README.md) will be shown on the GitHub's >> landing page of the project (instead of .github/README.md). >> >> Jacopo >> >> >> On Tue, Apr 7, 2026 at 7:57 AM Jacques Le Roux via dev < >> [email protected]> >> wrote: >> >> > Hi Anahita, >> > >> > I don't know if it would work, we could have done the inverse. >> > Rewrite .github/README.md to Asciidoc. The file is quite shorter (59 >> lines >> > vs 974). If you did not try already, we could using a dummy file >> > .github/README.adoc to see how it goes? >> > >> > Jacques >> > >> > Le 05/04/2026 à 20:24, Jacques Le Roux via dev a écrit : >> > > Hi and thanks Anahita (for some time now, I tend to forget even my >> > birthday, but Easter is really something you can't ignore. Nature shows >> it >> > to >> > > you, more than Christmas I'd say, at least in this part of the >> > hemisphere), >> > > >> > > Actually, as you may know I'm ageing, (it's not so bad though :). I >> > forgot my 1st answer and the sense of Jacopo's proposition that I just >> > reread, >> > > with my answer then. >> > > >> > > Of course you are right. I guess it's the solution. >> > > >> > > Thanks for your work >> > > >> > > Jacques >> > > >> > > Le 05/04/2026 à 18:38, Anahita Goljahani a écrit : >> > > >> > >> Hi Jacques (happy Easter), >> > >> >> > >> I agree with you that the content of the README.adoc should be >> displayed >> > >> when you land on the project’s GitHub page. >> > >> However, as far as I understand, if we convert the current >> README.adoc >> > >> (AsciiDoc) into .md (Markdown) format, the problem should be resolved >> > and >> > >> the correct content should be displayed. >> > >> >> > >> Just so you know, I’m planning to convert the file in the next few >> days. >> > >> >> > >> Best regards >> > >> >> > >> Anahita >> > >> >> > >> Il giorno sab 4 apr 2026 alle ore 10:32 Jacques Le Roux via dev < >> > >> [email protected]> ha scritto: >> > >> >> > >>> Hi Jacopo, >> > >>> >> > >>> BTW, that changed when you added >> > >>> >> https://github.com/apache/ofbiz-framework/blob/trunk/.github/README.md >> > . >> > >>> Before >> > https://github.com/apache/ofbiz-framework/blob/trunk/README.adoc >> > >>> showed. >> > >>> >> > >>> So the question is: should prefer one or the other? >> > >>> >> > >>> I believe the README.adoc should be preferred. >> > >>> Because it shows what OFBiz is and its status. >> > >>> When README.md is only about our GitHub CI/CD Configuration. >> > >>> The second is of less interest for new comers and visitors. >> > >>> >> > >>> Jacques >> > >>> >> > >>> Le 31/03/2026 à 16:42, Jacques Le Roux via dev a écrit : >> > >>>> We can try >> > >>>> >> > >>>> Jacques >> > >>>> >> > >>>> Le 31/03/2026 à 12:29, Ashish Vijaywargiya a écrit : >> > >>>>> +1 >> > >>>>> >> > >>>>> Thanks, >> > >>>>> Ashish Vijaywargiya >> > >>>>> >> > >>>>> On Tue, 31 Mar 2026 at 15:25, Jacopo Cappellato < >> > >>> [email protected]> >> > >>>>> wrote: >> > >>>>> >> > >>>>>> Hi all, >> > >>>>>> >> > >>>>>> I’ve noticed that because we currently have a README.md file >> inside >> > the >> > >>>>>> .github/ folder, that file is being displayed on the landing >> page of >> > >>> the >> > >>>>>> project (https://github.com/apache/ofbiz-framework) instead of >> the >> > >>>>>> README.adoc located in the root directory. >> > >>>>>> >> > >>>>>> One possible workaround would be to rename .github/README.md to >> > avoid >> > >>> this >> > >>>>>> unintended behavior. However, I’d like to propose a different >> > approach: >> > >>>>>> converting the root README.adoc (AsciiDoc) into a README.md >> > (Markdown). >> > >>>>>> >> > >>>>>> This change could improve compatibility with GitHub’s default >> > behavior >> > >>> and >> > >>>>>> make the project more accessible to a wider audience, since >> > Markdown is >> > >>>>>> more commonly used and immediately rendered as expected on GitHub >> > >>> project >> > >>>>>> pages. >> > >>>>>> >> > >>>>>> Of course, this would also require evaluating any >> AsciiDoc-specific >> > >>>>>> features currently in use and ensuring they are properly >> translated >> > or >> > >>>>>> adapted. >> > >>>>>> >> > >>>>>> What do you think about this approach? >> > >>>>>> >> > >>>>>> Best regards, >> > >>>>>> >> > >>>>>> Jacopo >> > >>>>>> >> >
