Port Polykey.io Theme to polykey.io/docs

[CMCDragonkai]

Specification

The Polykey.io theme should be brought into the documentation site. The main polykey.io is located in https://gitlab.com/MatrixAI/Engineering/Polykey/polykey.io.

The current documentation site is based off Docusaurus classic theme. https://docusaurus.io/docs/api/themes/@docusaurus/theme-classic. This means the current docs site looks very similar to the official docusaurus site and to many other docusaurus documentation websites.

Docusaurus classic theme itself uses a "framework" called Infima https://infima.dev/. This means all of component structure is based on Infima.

We want to preserve this classic theme as much as possible, while customising the theme/overriding parts of the theme to fit the Polykey.io design elements.

In order to do this, Docusaurus provides 3 different ways of changing the existing theme:

1. Override the CSS with a global CSS file.
2. Wrapping an existing React component with a custom React component, which is loaded ahead in priority.
3. Replacing an existing React component with a custom React component, which is loaded ahead in priority.

For overriding the CSS, see: https://docusaurus.io/docs/styling-layout.

It will require a new ./src/css/custom.css file, which is loaded into the ./docusaurus.config.js file.

The CSS file can specify theme class names, infima class names, or CSS module class names. Prefer using the theme class names, then the infima class names before creating custom CSS module class names.

When it comes to overriding the React components prefer wrapping before replacing as this is more stable in the long term. I have already made an example of overriding an existing React component. This is located in:

»» ~/Projects/Polykey-Docs
 ♖ tree src                                                                                                                              (master) pts/2 16:20:06
src
└── theme
    └── Navbar
        └── index.tsx

2 directories, 1 file

This was produced through the command:

npm run swizzle @docusaurus/theme-classic NavBar -- --wrap --typescript

This will create a new ./src/theme/Navbar/index.tsx file. This file is loaded ahead of the original ./node_modules/@docusaurus/theme-classic/src/theme/Navbar/index.tsx file. This means that the new file will be loaded instead of the original file.

Docusaurus calls this overriding concept "swizzling". This is explained here: https://docusaurus.io/docs/swizzling.

Take note of the all the components available to be swizzled with npm run swizzle -- --list.

Navigation Bar

The navigation bar in polykey.io/docs must be made to look exactly the same as the one in polykey.io. This means the Docs link must go to polykey.io/docs. The other links on the navigation bar must open within the same frame (target must be _self). This ensures that the docs looks like just another subpage as part of the main website.

The docs navbar currently has 2 additional things that should be removed:

The GitHub link should be unnecessary. We already have a GitHub icon on the navbar on https://polykey.io/.

Note that I have already removed the dark mode button.

During mobile usage, notice that the navbar collapses.

This collapse looks different from the current polykey.io website. On the polykey.io website, the menu is put on the right-hand side.

The menu for docusaurus is superior to the menu currently on polykey.io. However some changes should be made.

The menu button should be moved to the right-hand side to be similar to polykey.io.

However leave the menu contents the same. We will only address this once we start migrating polykey.io to docusaurus.

The links here are specified in ./docusaurus.config.js under config.themeConfig.navbar.items.

Ensure that hover colours are also the same.

Ensure that the email configuration is the same. It should be subscribing to the action:

//matrix.us9.list-manage.com/subscribe/post?u=c95e0a682d8937f12732b48d4&id=863aebab0f

Footer

The footer on Docusaurus is far more sophisticated compared to the footer in https://polykey.io/.

We want to keep all the links in the polykey.io/docs/ except the Company column.

The Company column is replaced with the footer from polykey.io.

The logo in the polykey.io/docs should be removed. Replace it with the logo plus "POLYKEY" as in polykey.io.

Where it says Polykey is a product of Matrix AI, add an additional text underneath it with the copyright message. It should say the current year. See: facebook/docusaurus#6628

The entire footer colours should match it on https://polykey.io/.

Fonts

The https://polykey.io uses Open Sans and has a backup to sans-serif.

We are supposed to 3 kinds of fonts on our website:

1. Open Sans (backup: sans-serif) - used for headings and buttons and regular text and links
2. Roboto Mono (backup: monospace) - this is supposed to be used for code blocks

Buttons are always fully capital bold open sans.

Headings are usually bold open sans.

Smaller headings are usually semi-bold open sans.

The TTF versions of the fonts are available here: https://github.com/MatrixAI/Polykey-Desktop/tree/staging/src/renderer/fonts. Copy the 2 font directories to this project and put in the right place (static?).

Colours

We have background tones, content tones, accent colours and semantic colours.

These are the colours to be used:

// Grey
grey1: '#FFFFFF',
grey2: '#FDFEFF',
grey3: '#FAFAFA',
grey4: '#E7E9F2',
grey5: '#E8F0F0',
grey6: '#EEEFF2',

// Primary
primary1: '#116466',
primary2: '#289295',
primary3: '#7BBBBC',
primary4: '#D1E8E2',

// Semantic
semantic1: '#F15446',

// Content tones
content1: '#1F211B',
content2: '#7F88A5',
content3: '#C2C9DF',
content4: '#E4E9F2',

The content colours are used for text.

The primary colours are used for buttons and headings.

The semantic colour is used for errors.

The grey colours are used for background.

In the docusaurus website, it uses the Infima colours. Which uses 7 shades of colours per category.

https://infima.dev/docs/utilities/colors

Map the greys to the secondary colours. These will be the "background kind of colors".

Map the primary colours to the primary colours. These are the headings and links.

Map the content colours to the content colours. These are the text.

See this issue: facebook/docusaurus#3955

This may require some fiddling to get right.

Tasks

1. Fix the side bar so we can use a custom layout
2. Bring in the Polykey theme as a custom theme

[CMCDragonkai]

Also the side bar is still isn't entirely fixed. This needs to regain the original _Sidebar.md design and categorisation.

[CMCDragonkai]

The current site in webflow may be exported, but it may generate somewhat messy HTML and CSS code. It will need to be sliced out and turned into a docusaurus theme so we can preserve the structure.

Once we do this, we can also port the entire polykey.io to docusaurus and use it as a statically generated site.

[CMCDragonkai]

The sidebar is now fixed up.

I've also moved the src to server.

This is because swizzling process in Docusaurus involves using the src directory.

I've demonstrated an example of a wrapped component with ba3cb6d:

npm run swizzle @docusaurus/theme-classic NavBar -- --wrap --typescript

This ends up creating:

[nix-shell:~/Projects/Polykey-Docs]$ tree src/
src/
└── theme
    └── Navbar
        └── index.tsx

2 directories, 1 file

The index.tsx is a thin wrapper around the Navbar component, and I tested adding HTML there and it worked.

Other navbar components are available:

│ Navbar                                   │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Navbar/ColorModeToggle                   │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Navbar/Content                           │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Navbar/Layout                            │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Navbar/Logo                              │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Navbar/MobileSidebar                     │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Navbar/MobileSidebar/Header              │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Navbar/MobileSidebar/Layout              │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Navbar/MobileSidebar/PrimaryMenu         │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Navbar/MobileSidebar/SecondaryMenu       │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Navbar/MobileSidebar/Toggle              │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Navbar/Search                            │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ NavbarItem                               │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ NavbarItem/DefaultNavbarItem             │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ NavbarItem/DocNavbarItem                 │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ NavbarItem/DocSidebarNavbarItem          │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ NavbarItem/DocsVersionDropdownNavbarItem │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ NavbarItem/DocsVersionNavbarItem         │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ NavbarItem/DropdownNavbarItem            │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ NavbarItem/HtmlNavbarItem                │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ NavbarItem/LocaleDropdownNavbarItem      │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ NavbarItem/NavbarNavLink                 │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │
├──────────────────────────────────────────┼───────────┼───────────┼─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ NavbarItem/SearchNavbarItem              │ Unsafe    │ Unsafe    │ N/A                                                                                                                                         │

Swizzling the navbar component and components is only useful in order to change the layout of the navbar in case we need it to fit within what our main website looks like. Most changes should be doable with just the global CSS override.

[CMCDragonkai]

The spec above has been updated to include the initial changes:

1. NavBar
2. Footer
3. Fonts
4. Colours

[CMCDragonkai]

Got an answer regarding the moving of the menu to the right side:

[developerdesigner18]

1)Changes in the Header :

-->https://imgur.com/OYLO7az

-->Make the document site's navbar similar to the Original site in responsive mode also

[CMCDragonkai]

Welcome @developerdesigner18. I have added you to the Matrix AI org. Please accept your invitation in your email.

[CMCDragonkai]

I've given you triage role for this project. When you start tomorrow, please create a new PR for this repository targeting the master branch.

[CMCDragonkai]

@bmamouri finished this with #17 PR. It's been merged, now awaiting staging.

[CMCDragonkai]

@amydevs please have a look when you are reviewing.