From bbf0f65284f6c9cc40429f446bddf48e2e882ad0 Mon Sep 17 00:00:00 2001 From: Joel Challis Date: Sun, 27 Dec 2020 16:56:10 +0000 Subject: [PATCH] Simplify the visual flow of the getting started page (#11316) * Add tabs to getting started page * Review comments Co-authored-by: Ryan * Align with current theme * Update docs/newbs_getting_started.md Co-authored-by: Ryan * Apply suggestions from code review Co-authored-by: Ryan Co-authored-by: Ryan --- docs/index.html | 5 ++ docs/newbs_getting_started.md | 89 +++++++++++++++++++++++++++++------ docs/qmk_custom_dark.css | 17 +++++++ docs/qmk_custom_light.css | 17 +++++++ 4 files changed, 114 insertions(+), 14 deletions(-) diff --git a/docs/index.html b/docs/index.html index 5cab97a57f..5312b9105d 100644 --- a/docs/index.html +++ b/docs/index.html @@ -126,6 +126,10 @@ headings: 'h1, h2', title: 'Table of Contents', }, + tabs: { + persist : false, + tabComments: false, + }, plugins: [ function (hook, vm) { hook.beforeEach(function (html) { @@ -148,6 +152,7 @@ + diff --git a/docs/newbs_getting_started.md b/docs/newbs_getting_started.md index 5eb99377c1..3793fe7673 100644 --- a/docs/newbs_getting_started.md +++ b/docs/newbs_getting_started.md @@ -37,26 +37,45 @@ We've tried to make QMK as easy to set up as possible. You only have to prepare [Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)
[Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html) -### Windows + -You will need to install MSYS2, Git, and the QMK CLI. +### ** Windows ** -Follow the installation instructions on the [MSYS2 homepage](http://www.msys2.org). Close any open MSYS terminals and open a new MinGW 64-bit terminal. **NOTE: This is *not* the same as the MSYS terminal that opens when installation is completed.** +#### Prerequisites -Then, run the following: +You will need to install MSYS2, Git and Python. Follow the installation instructions on https://www.msys2.org. + +Once MSYS2 is installed, close any open MSYS terminals and open a new MinGW 64-bit terminal. + +!> **NOTE:** The MinGW 64-bit terminal is *not* the same as the MSYS terminal that opens when installation is completed. Your prompt should say "MINGW64" in purple text, rather than "MSYS". See [this page](https://www.msys2.org/wiki/MSYS2-introduction/#subsystems) for more information on the differences. + +Then run the following command: pacman --needed --noconfirm --disable-download-timeout -S git mingw-w64-x86_64-toolchain mingw-w64-x86_64-python3-pip + +#### Installation + +Install the QMK CLI by running: + python3 -m pip install qmk -### macOS +### ** macOS ** -You will need to install Homebrew. Follow the instructions on the [Homebrew homepage](https://brew.sh). +QMK maintains a Homebrew tap and formula which will automatically install the CLI and all necessary dependencies. -After Homebrew is installed run this command: +#### Prerequisites + +You will need to install Homebrew. Follow the instructions on https://brew.sh. + +#### Installation + +Install the QMK CLI by running: brew install qmk/qmk/qmk -### Linux +### ** Linux/WSL ** + +#### Prerequisites You will need to install Git and Python. It's very likely that you already have both, but if not, one of the following commands should install them: @@ -68,29 +87,61 @@ You will need to install Git and Python. It's very likely that you already have * Sabayon: `sudo equo install dev-vcs/git dev-python/pip` * Gentoo: `sudo emerge dev-vcs/git dev-python/pip` -Install the global CLI to bootstrap your system: +#### Installation -`python3 -m pip install --user qmk` (on Arch-based distros you can also try the `qmk` package from AUR (**note**: it's maintained by a community member): `yay -S qmk`) +Install the QMK CLI by running: -### FreeBSD + python3 -m pip install --user qmk + +On Arch-based distros you can also try the `qmk` package from AUR (**NOTE**: this package is maintained by a community member, and at the time of writing marks some dependencies as optional that should not be): + + yay -S qmk + +### ** FreeBSD ** + +#### Prerequisites You will need to install Git and Python. It's possible that you already have both, but if not, run the following commands to install them: pkg install git python3 -Make sure that `$HOME/.local/bin` is added to your `$PATH` so that locally install Python packages are available. +Make sure that `$HOME/.local/bin` is added to your `$PATH` so that locally installed Python packages are available. -Once installed, you can install QMK CLI: +#### Installation + +Install the QMK CLI by running: python3 -m pip install --user qmk + + ## 3. Run QMK Setup :id=set-up-qmk + + +### ** Windows ** + After installing QMK you can set it up with this command: qmk setup -In most situations you will want to answer Yes to all of the prompts. +In most situations you will want to answer `y` to all of the prompts. + +### ** macOS ** + +After installing QMK you can set it up with this command: + + qmk setup + +In most situations you will want to answer `y` to all of the prompts. + +### ** Linux/WSL ** + +After installing QMK you can set it up with this command: + + qmk setup + +In most situations you will want to answer `y` to all of the prompts. ?>**Note on Debian, Ubuntu and their derivatives**: It's possible, that you will get an error saying something like: `bash: qmk: command not found`. @@ -98,12 +149,22 @@ This is due to a [bug](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=839155) Sadly, Ubuntu reitroduced this bug and is [yet to fix it](https://bugs.launchpad.net/ubuntu/+source/bash/+bug/1588562). Luckily, the fix is easy. Run this as your user: `echo 'PATH="$HOME/.local/bin:$PATH"' >> $HOME/.bashrc && source $HOME/.bashrc` +### ** FreeBSD ** + +After installing QMK you can set it up with this command: + + qmk setup + +In most situations you will want to answer `y` to all of the prompts. + ?>**Note on FreeBSD**: It is suggested to run `qmk setup` as a non-`root` user to start with, but this will likely identify packages that need to be installed to your base system using `pkg`. However the installation will probably fail when run as an unprivileged user. To manually install the base dependencies, run `./util/qmk_install.sh` either as `root`, or with `sudo`. Once that completes, re-run `qmk setup` to complete the setup and checks. + + ?> If you already know [how to use GitHub](getting_started_github.md), we recommend that you create your own fork and use `qmk setup /qmk_firmware` to clone your personal fork. If you don't know what that means you can safely ignore this message. ## 4. Test Your Build Environment diff --git a/docs/qmk_custom_dark.css b/docs/qmk_custom_dark.css index a7feb159c8..c7fe7b7da7 100644 --- a/docs/qmk_custom_dark.css +++ b/docs/qmk_custom_dark.css @@ -27,3 +27,20 @@ .markdown-section hr, .search { border-bottom: 1px solid #777 !important; } + + +:root { + --docsifytabs-border-color: #555; + --docsifytabs-tab-highlight-color: var(--theme-color,#ea6f5a); + + --docsifytabs-tab-background: #444; + --docsifytabs-tab-background-active: #3f3f3f; +} + +.docsify-tabs__tab:focus { + outline: none !important; +} + +.docsify-tabs__content .anchor { + transition: none; +} diff --git a/docs/qmk_custom_light.css b/docs/qmk_custom_light.css index 07b26ecec9..c5d36cf6f0 100644 --- a/docs/qmk_custom_light.css +++ b/docs/qmk_custom_light.css @@ -28,3 +28,20 @@ .markdown-section pre { padding: 0; } + + +:root { + --docsifytabs-border-color: #ddd; + --docsifytabs-tab-highlight-color: var(--theme-color, #0074d9); + + --docsifytabs-tab-background: #f8f8f8; + --docsifytabs-tab-background-active: transparent; +} + +.docsify-tabs__tab:focus { + outline: none !important; +} + +.docsify-tabs__content .anchor { + transition: none; +}