1
0
Fork 0

Simplify the visual flow of the getting started page (#11316)

* Add tabs to getting started page

* Review comments

Co-authored-by: Ryan <fauxpark@gmail.com>

* Align with current theme

* Update docs/newbs_getting_started.md

Co-authored-by: Ryan <fauxpark@gmail.com>

* Apply suggestions from code review

Co-authored-by: Ryan <fauxpark@gmail.com>

Co-authored-by: Ryan <fauxpark@gmail.com>
This commit is contained in:
Joel Challis 2020-12-27 16:56:10 +00:00 committed by GitHub
parent 1d1d5da43f
commit bbf0f65284
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 114 additions and 14 deletions

View file

@ -126,6 +126,10 @@
headings: 'h1, h2', headings: 'h1, h2',
title: 'Table of Contents', title: 'Table of Contents',
}, },
tabs: {
persist : false,
tabComments: false,
},
plugins: [ plugins: [
function (hook, vm) { function (hook, vm) {
hook.beforeEach(function (html) { hook.beforeEach(function (html) {
@ -148,6 +152,7 @@
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script> <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
<script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script> <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
<script src="//unpkg.com/docsify/lib/plugins/emoji.min.js"></script> <script src="//unpkg.com/docsify/lib/plugins/emoji.min.js"></script>
<script src="//unpkg.com/docsify-tabs@1"></script>
<script src="//unpkg.com/docsify-copy-code@2"></script> <script src="//unpkg.com/docsify-copy-code@2"></script>
<script src="//unpkg.com/docsify-toc@1.0.0/dist/toc.js"></script> <script src="//unpkg.com/docsify-toc@1.0.0/dist/toc.js"></script>
<script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script> <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>

View file

@ -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)<br> [Must Know Linux Commands](https://www.guru99.com/must-know-linux-commands.html)<br>
[Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html) [Some Basic Unix Commands](https://www.tjhsst.edu/~dhyatt/superap/unixcmd.html)
### Windows <!-- tabs:start -->
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 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 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 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: 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` * Sabayon: `sudo equo install dev-vcs/git dev-python/pip`
* Gentoo: `sudo emerge 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: 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 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 python3 -m pip install --user qmk
<!-- tabs:end -->
## 3. Run QMK Setup :id=set-up-qmk ## 3. Run QMK Setup :id=set-up-qmk
<!-- tabs:start -->
### ** Windows **
After installing QMK you can set it up with this command: After installing QMK you can set it up with this command:
qmk setup 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**: ?>**Note on Debian, Ubuntu and their derivatives**:
It's possible, that you will get an error saying something like: `bash: qmk: command not found`. 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). 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` 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**: ?>**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 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. 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`. 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. Once that completes, re-run `qmk setup` to complete the setup and checks.
<!-- tabs:end -->
?> If you already know [how to use GitHub](getting_started_github.md), we recommend that you create your own fork and use `qmk setup <github_username>/qmk_firmware` to clone your personal fork. If you don't know what that means you can safely ignore this message. ?> If you already know [how to use GitHub](getting_started_github.md), we recommend that you create your own fork and use `qmk setup <github_username>/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 ## 4. Test Your Build Environment

View file

@ -27,3 +27,20 @@
.markdown-section hr, .search { .markdown-section hr, .search {
border-bottom: 1px solid #777 !important; 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;
}

View file

@ -28,3 +28,20 @@
.markdown-section pre { .markdown-section pre {
padding: 0; 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;
}