Complete Redesign of the Installation Page #51

Fatih20 · 2021-08-14T12:49:00Z

Continuation of #50

To do:

Use overrides to remove the pesky footer at the bottom and pencil tool at the header, without losing markdown extension that is used for generating tabs.
Correct the way that the individual OS' installation page links to other OS's installation page
Investigate why the variables in extras isn't read by the installation overrides

Fatih20 · 2021-08-14T12:59:31Z

2021-08-14.19-56-49.mp4

The site as of right now.

Fatih20 · 2021-08-15T03:01:19Z

I've looked into the macros plugin and from what I've tried, it is possible to include markdown files in HTML files. The problem now is that the documentation doesn't seem to mention a way to include just part of the included markdown files. But that would mean every time I'm using a new tag, a new markdown file is required (assuming if we want to sanitize the markdown file from HTML syntax).

Fatih20 · 2021-08-15T10:53:15Z

@Technius can you elaborate further on how we are going to make overrides but still having the content in the markdown files? Because I don't really understand.

Technius · 2021-08-15T19:04:28Z

We create an override for installation/. This override should contain the common elements, like the markup for the buttons at the top. We can select which button is "active" by reading metadata from the markdown files (e.g., at the top of the Windows file, we can set active_button: windows and then using if/else to determine which button should get the active class). To include the markdown content, we can use the page.content variable.

The individual markdown files should have the OS-specific instructions. In this case, the markdown files should just contain the contents of the installation-guide div.

Fatih20 · 2021-08-15T22:29:09Z

Here's thing though. I'm assuming making the overrides for the installation page is the same process as making the overrides for the homepage. I repeated the process of moving the file to an HTML to the overrides folder with all of its CSS. For some reason, the page wouldn't read the CSS and go about unstyled. Even weirder is that the table of content is still visible even though we're supposed to override the theme. This didn't happen with the homepage.

Fatih20 · 2021-08-16T00:06:39Z

We create an override for installation/. This override should contain the common elements, like the markup for the buttons at the top. We can select which button is "active" by reading metadata from the markdown files (e.g., at the top of the Windows file, we can set active_button: windows and then using if/else to determine which button should get the active class). To include the markdown content, we can use the page.content variable.

The individual markdown files should have the OS-specific instructions. In this case, the markdown files should just contain the contents of the installation-guide div.

Wouldn't this mean clicking the OS selection button wouldn't link to the OS page? So is it replaced with an if/else logic that select which content is displayed according to what button is "active"? But what happens when there is no active button, such as when the user first visit the installation page?

Fatih20 · 2021-08-16T04:09:22Z

On a second thought, could simplifying the override be a part of a different PR? Considering that some part are more complex to simplify and optimize, (Linux installation page has different download buttons, and the title of the version selection has a subtitle that isn't present in Windows and MacOS installation page), for the best implementation I think it should be a different PR.

Fatih20 · 2021-08-16T10:06:26Z

For some reason that I don't know, MkDocs just wouldn't read the CSS linked to the installation.html. <style> still works, for some reason. The only reason it is being somewhat styled is the CSS from the /docs/css directory. If they are removed (which they should because they're specific to the installation page), it'll be like this.

Even worse is that for some reason, the table of content is still present. The homepage didn't do any of this in my previous pull request.

Technius · 2021-08-16T19:59:25Z

Yeah, let's just keep it simple for now. I can help you clean it up in another PR.

Fatih20 · 2021-08-25T02:39:25Z

Alright, that problem is fixed. But now when building, MkDocs says that 'downloads' (which is in the individual OS installation page) is undefined. Even though it is defined in the .yml file. Any help? @Technius

Fatih20 · 2021-08-25T04:04:23Z

I added the whole downloads variable to the header of the markdown only as a temporary measure. Once the layout is corrected I'll fix it.

Technius · 2021-08-25T06:37:30Z

You'll probably need to resort to the markdown file for Linux, otherwise you'll have to enter <code> tags manually.

I added the whole downloads variable to the header of the markdown only as a temporary measure.

For the links, the "correct" solution would probably be something like defining the links in a yml file and then including it with a macro: https://mkdocs-macros-plugin.readthedocs.io/en/latest/advanced/#including-external-yaml-files

Technius · 2021-08-25T07:23:58Z

The issue seems to be that markdown can't be used inside of manually inserted HTML tags. The simplest workaround I can think of is to put the tab element thing (the one that contains all of the tabs) into a markdown file and then use the include macro.

Fatih20 · 2021-08-25T07:25:59Z

The issue seems to be that markdown can't be used inside of manually inserted HTML tags. The simplest workaround I can think of is to put the tab element thing (the one that contains all of the tabs) into a markdown file and then use the include macro.

I've done this. Now I just need to theme it.

Fatih20 · 2021-08-25T14:05:31Z

I don't get why using {{ ' ../linux' | url }} in the Windows installation page to link to the Linux installation page links to http://127.0.0.1:8000/linux. Shouldn't it go up a directory and then go to linux? Why is it not using relative path?

Fatih20 · 2021-08-26T23:20:48Z

Even after including the many downloads variable in an external yaml file, the issue still persists.

ERROR    -  Error building page 'installation/linux.md': 'dict object' has no attribute 'downloads'
Traceback (most recent call last):
  File "/home/fatih/.local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/usr/lib/python3/dist-packages/click/core.py", line 764, in __call__
    return self.main(*args, **kwargs)
  File "/usr/lib/python3/dist-packages/click/core.py", line 717, in main
    rv = self.invoke(ctx)
  File "/usr/lib/python3/dist-packages/click/core.py", line 1137, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/lib/python3/dist-packages/click/core.py", line 956, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/lib/python3/dist-packages/click/core.py", line 555, in invoke
    return callback(*args, **kwargs)
  File "/home/fatih/.local/lib/python3.8/site-packages/mkdocs/__main__.py", line 173, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, **kwargs)
  File "/home/fatih/.local/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 54, in serve
    config = builder()
  File "/home/fatih/.local/lib/python3.8/site-packages/mkdocs/commands/serve.py", line 49, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/home/fatih/.local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 306, in build
    _build_page(file.page, config, doc_files, nav, env, dirty)
  File "/home/fatih/.local/lib/python3.8/site-packages/mkdocs/commands/build.py", line 217, in _build_page
    output = template.render(context)
  File "/usr/lib/python3/dist-packages/jinja2/asyncsupport.py", line 76, in render
    return original_render(self, *args, **kwargs)
  File "/usr/lib/python3/dist-packages/jinja2/environment.py", line 1008, in render
    return self.environment.handle_exception(exc_info, True)
  File "/usr/lib/python3/dist-packages/jinja2/environment.py", line 780, in handle_exception
    reraise(exc_type, exc_value, tb)
  File "/usr/lib/python3/dist-packages/jinja2/_compat.py", line 37, in reraise
    raise value.with_traceback(tb)
  File "/home/fatih/Documents/Github Stuff/Xournal Site/Better Installation Page/overrides/installation/linux.html", line 1, in <module>
    {% extends "base.html" %}
  File "/home/fatih/.local/lib/python3.8/site-packages/material/base.html", line 121, in <module>
    {% block tabs %}
  File "/home/fatih/Documents/Github Stuff/Xournal Site/Better Installation Page/overrides/installation/linux.html", line 31, in <module>
    <a class="download button download-linux" href="{{page.meta.downloads.linux.appimage}}">AppImage</a>
  File "/usr/lib/python3/dist-packages/jinja2/environment.py", line 430, in getattr
    return getattr(obj, attribute)
jinja2.exceptions.UndefinedError: 'dict object' has no attribute 'downloads'

Technius · 2021-08-27T08:01:30Z

The tabs display correctly for me; did you restart your server?

Unfortunately, it seems like macros only work in markdown files, not in templates (fralau/mkdocs-macros-plugin#60 (comment)).

~~Let's just do the metadata at the top of the page for now.~~ I will clean it up later.

Technius · 2021-08-27T08:11:11Z

By the way, I'm not sure that we need the extra downloads.yml file. Aren't the download links already defined in the extras section of mkdocs.yml?

Fatih20 · 2021-08-27T09:09:13Z

The tabs display correctly for me; did you restart your server?

It's been correct since yesterday. I just had to break it up to a separate markdown file.

By the way, I'm not sure that we need the extra downloads.yml file. Aren't the download links already defined in the extras section of mkdocs.yml?

It is. But I thought I had to try breaking it up into another file, that's what the link you sent was about.

Fatih20 · 2021-08-28T02:35:13Z

While this doesn't mitigate the problem completely, I believe this is a more elegant stopgap solution than merely putting the links in the header of the markdown. @Technius

Technius · 2021-08-28T20:19:00Z

Let's just get something working for now. I will clean it up later.

Fatih20 · 2021-08-29T00:02:12Z

Let's just get something working for now. I will clean it up later.

It's already working. Have you not tried it?

Technius · 2021-08-29T18:46:26Z

The install pages look fine to me for now.

I don't get why using {{ ' ../linux' | url }} in the Windows installation page to link to the Linux installation page links to http://127.0.0.1:8000/linux. Shouldn't it go up a directory and then go to linux? Why is it not using relative path?

I think this is a mkdocs bug; the url filter should be generating the linux relative to the current page, but it's generating the link relative to the site's base url instead. For now, let's just directly write the url instead of using the filter.

Fatih20 · 2021-08-29T22:17:02Z

Done.

Technius

I think this is good to go. I will handle the squash and final merge.

This is a combination of 11 commits: * Most redesign of the page is done * Purge h1 for SEO optimization * Fix the installation.html not reading CSS files * Add CSS properties that were previously covered by the themes * Fix theming on tabs and automating its content * Make download button be vertically-aligned between the Nightly and Stable version so that it's more aesthetically pleasing * Removes unnecessary padding * Fix links to other OS installation pages with absolute path * Tweaks the tab in linux installation page by lighting up the color of not selected distro and giving animation to the colored underline * Put links as a variable in a markdown file that then get included in the HTML * Change links to not use the filter

Technius · 2021-09-16T01:37:37Z

Sorry it took so long, I've been busy recently.

Technius · 2021-09-18T06:33:42Z

I pushed some commits to master branch to refactor the installation page template code. Some minor visual changes happened; can you check to see if it looks okay?

Fatih20 · 2021-09-18T06:35:29Z

I pushed some commits to master branch to refactor the installation page template code. Some minor visual changes happened; can you check to see if it looks okay?

Just saw it. Can't find any difference.

Technius · 2021-09-18T06:42:54Z

Thanks for checking!

Technius mentioned this pull request Aug 24, 2021

Improve installation instructions for MacOS #53

Merged

2 tasks

Technius approved these changes Aug 29, 2021

View reviewed changes

Technius linked an issue Sep 16, 2021 that may be closed by this pull request

Better Installation Page #50

Closed

Fatih20 added 2 commits September 15, 2021 18:29

Move overrides outside of the docs directory

06c1838

Technius force-pushed the Installation-page-redesign branch from 78c63b9 to a1233ba Compare September 16, 2021 01:36

Technius merged commit c077d03 into xournalpp:site Sep 16, 2021

Complete Redesign of the Installation Page #51

Complete Redesign of the Installation Page #51

Uh oh!

Conversation

Fatih20 commented Aug 14, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Fatih20 commented Aug 14, 2021

Uh oh!

Fatih20 commented Aug 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Fatih20 commented Aug 15, 2021

Uh oh!

Technius commented Aug 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Fatih20 commented Aug 15, 2021

Uh oh!

Fatih20 commented Aug 16, 2021

Uh oh!

Fatih20 commented Aug 16, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Fatih20 commented Aug 16, 2021

Uh oh!

Technius commented Aug 16, 2021

Uh oh!

Fatih20 commented Aug 25, 2021

Uh oh!

Fatih20 commented Aug 25, 2021

Uh oh!

Technius commented Aug 25, 2021

Uh oh!

Technius commented Aug 25, 2021

Uh oh!

Fatih20 commented Aug 25, 2021

Uh oh!

Fatih20 commented Aug 25, 2021

Uh oh!

Fatih20 commented Aug 26, 2021

Uh oh!

Technius commented Aug 27, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Technius commented Aug 27, 2021

Uh oh!

Fatih20 commented Aug 27, 2021

Uh oh!

Fatih20 commented Aug 28, 2021

Uh oh!

Technius commented Aug 28, 2021

Uh oh!

Fatih20 commented Aug 29, 2021

Uh oh!

Technius commented Aug 29, 2021

Uh oh!

Fatih20 commented Aug 29, 2021

Uh oh!

Technius left a comment

Choose a reason for hiding this comment

Uh oh!

Technius commented Sep 16, 2021

Uh oh!

Technius commented Sep 18, 2021

Uh oh!

Fatih20 commented Sep 18, 2021

Uh oh!

Technius commented Sep 18, 2021

Uh oh!

Uh oh!

Fatih20 commented Aug 14, 2021 •

edited

Loading

Fatih20 commented Aug 15, 2021 •

edited

Loading

Technius commented Aug 15, 2021 •

edited

Loading

Fatih20 commented Aug 16, 2021 •

edited

Loading

Technius commented Aug 27, 2021 •

edited

Loading