Closed sanderdlm closed 3 years ago
I tried to rebase from the upstream master branch once the typo branch got merged to solve any possible merge conflicts, but it seems like I messed up and now I see a bunch of duplicate commits. If I need to undo something let me know.
I undid the merge with a force push and then simply merged the master branch into this one. Should be able to merge without conflicts now.
High level feedback from the first look:
On the main page, there isn’t enough spacing above the download button.
On the docs page, there also needs to be more spacing—everything looks pretty cramped.
E.g. /docs/userguide.html doesn’t render correctly (maybe a few required CSS classes were removed accidentally?)
For point 1 & 2: I've already fixed the problems with each specific page on a separate branch, which I was planning to PR after this general one. If you want I can cherry-pick the commits, or just port the code over to this one. The bulk of the changes is removing floats and using flexbox for the layout of the homepage infobox, downloads page, screenshots page and docs overview page.
3: I haven't touched the docs because I saw that their HTML files are generated and don't use the default Jekyll template.
From what I have seen we have 2 options here to modernize the HTML code behind the docs; either figure out a way to generate the doc files as Jekyll templates, so with:
---
layout: default
title: Docs - Userguide
---
at the top. What if we place this snippet in the [header] tag of conf/i3html.conf. Would that work? I'm not that familiar with the asciidoc CLI so I don't know how flexible it is.
The second option would be to update the asciidoc back-end from xhtml1 to html5, although from what I can see on this page, the html5 back-end is 'functionally identical' to the xhtml1 one, so I don't know how much of an upgrade that would be. I looked further and bumped into asciidoctor, which seems more modern and is also what Github uses to support AsciiDoc format. Are you ok with me looking into this a bit further and finding a way to output cleaner HTML for the docs?
For backwards compatibility we could keep the xhtml1.css file and keep it linked to all the docs that are already built, and link to the new style.css file for any newer docs.
Edit: Are you familiar with this project? Seems very interesting.
For point 1 & 2: I've already fixed the problems with each specific page on a separate branch, which I was planning to PR after this general one. If you want I can cherry-pick the commits, or just port the code over to this one. The bulk of the changes is removing floats and using flexbox for the layout of the homepage infobox, downloads page, screenshots page and docs overview page.
Well, any PR I merge will be live within seconds. Hence, let’s do the changes in such a way that they never break something please :)
3: I haven't touched the docs because I saw that their HTML files are generated and don't use the default Jekyll template.
From what I have seen we have 2 options here to modernize the HTML code behind the docs; either figure out a way to generate the doc files as Jekyll templates, so with:
--- layout: default title: Docs - Userguide ---
at the top. What if we place this snippet in the [header] tag of conf/i3html.conf. Would that work? I'm not that familiar with the asciidoc CLI so I don't know how flexible it is.
I don’t know. Only one way to find out :)
The second option would be to update the asciidoc back-end from xhtml1 to html5, although from what I can see on this page, the html5 back-end is 'functionally identical' to the xhtml1 one, so I don't know how much of an upgrade that would be. I looked further and bumped into asciidoctor, which seems more modern and is also what Github uses to support AsciiDoc format. Are you ok with me looking into this a bit further and finding a way to output cleaner HTML for the docs?
Yes, but in a separate PR please. I’m using asciidoctor for https://robustirc.net/docs, and it is indeed nicer.
For backwards compatibility we could keep the xhtml1.css file and keep it linked to all the docs that are already built, and link to the new style.css file for any newer docs.
Sounds good.
Edit: Are you familiar with this project? Seems very interesting.
No, but note that it’s most likely not available in the jekyll that GitHub pages uses, so it’s not going to be of much use to us, I think.
I've added commits to update each major sub-section of the site except for the screenshots/gallery page. What is your opinion on removing the JS gallery entirely? While it still works, it doesn't scale well on mobile and has no swipe interaction. It has a couple of old dependencies that we could drop and it doesn't add that much value to the site from my point of view.
Docs are still broken so this PR can be regarded as WIP.
What is your opinion on removing the JS gallery entirely? While it still works, it doesn't scale well on mobile and has no swipe interaction. It has a couple of old dependencies that we could drop and it doesn't add that much value to the site from my point of view.
I’d rather leave it on there until it actually breaks in hard-to-fix ways. It’s better to have a convenient gallery on non-mobile than to have none at all.
What’s the status of these changes?
They need to be updated to address merge conflicts at the very least, but is the rest ready to review? There was no update after my most recent comment AFAICT.
I was working on the gallery and videos pages but completely forgot about it. There wasn't any interaction in this thread so I also figured you guys didn't really care for it. I'll take a look at it this afternoon and see if I can wrap up the PR excluding the docs conversion :)
I've fixed the merge conflicts and finished converting the screenshot gallery code to vanilla JS. Let me know what you think. I had to rebuild the docs because the header HTML structure changed slightly. I know we said to keep that in a separate PR, but I had to include just the header change in here to not break the site once merged.
I'll do some more work on making the docs HTML5 compatible and fully responsive if you decide to pick up this PR. I can also re-write the table of contents and footnotes JS (no fucntional changes, just refactoring the JS into this century).
Looks good! Could you rebase your changes please?
I gave it a quick try, but it’s a lot of changes and I don’t want to introduce any mistakes.
Hmm, GitHub still says:
This branch cannot be rebased due to conflicts Rebasing the commits of this branch on top of the base branch cannot be performed automatically due to conflicts encountered while reapplying the individual commits from the head branch.
You only merged, but didn’t rebase, yes?
I ran git rebase master
on my feature branch locally. I fixed the conflicts that appeared between my changes and the new commits on master. Then I force pushed this branch so the PR would update. Github still indicated conflicts so I fixed those manually using the Github interface.
Thanks for the details. I guess I’ll just go with a normal merge instead of a rebase merge, then.
It’ll be less easy to navigate in git (which is why I normally only do rebase merges), but at least your individual commits will be retained.
This PR updates all shared parts of the layout (header, nav, footer) and includes a basic CSS reset.
I have more work prepared for each of the main pages (docs, screenshots, downloads), but they all kind of depend on these initial 3 PRs. Then, after minimal changes to the major subpages, I can send one more PR that includes media queries and then the site should be mobile ready.