Skip to content

Commit 57c5e9d

Browse files
jthegedusjthegedus
authored
Significant documentation site improvements (asdf-vm#440)
# Summary This contains fixes and significant improvements to the documentation site. * fixes some routing issues due to erroneous docsify config * fixed links and layout of 404 pg * improved the language on the landing page as per asdf-vm#438 * propose a NEW_README.md tackling concerns with asdf-vm#438 and asdf-vm#422 * use docsify specific md to emphasise some text * add docsify-themeable plugin to improve loading experience and future proof for customisation * improve use of `asdf-vm` over `asdf` ## Other Information Included in this PR is a file `docs/NEW_README.md` which is my proposed README for this repo. The intention was to have all documentation in a single place, the site, and simplify the readme bringing the focus to explaining the tool rather than instructing users on how to use it. I will create a separate PR for the README, but in the meantime the landing page composes this new readme with the ballad.
1 parent 8d4ec0e commit 57c5e9d

10 files changed

Lines changed: 115 additions & 55 deletions

‎docs/NEW_README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<div style="position:absolute;">
2+
3+
[![Build Status](https://travis-ci.org/asdf-vm/asdf.svg?branch=master)](https://travis-ci.org/asdf-vm/asdf)
4+
5+
</div>
6+
7+
<div style="text-align:center">
8+
9+
# asdf-vm
10+
11+
**Manage multiple runtimes with a single CLI tool**
12+
13+
asdf-vm is a CLI tool that can manage multiple language runtimes on a per-project basis. It is like gvm, nvm, rbenv & pyenv (and more) all in one!
14+
15+
</div>
16+
17+
## Why use asdf-vm?
18+
19+
- single CLI for multiple languages
20+
- consistent commands to manage all your languages
21+
- single `.tool-versions` config file per project
22+
- single global config keeping defaults in one place
23+
- automatically switches runtime versions as you trasverse your directories
24+
- simple plugin system to add support for your language of choice
25+
- completion scripts managed by the plugin, not you!
26+
27+
## Documentation
28+
29+
[Please head over the documentation site for more information](https://asdf-vm.github.io/asdf/)!
30+
31+
- [Getting Started](https://asdf-vm.github.io/asdf/#/core-manage-asdf-vm)
32+
- [All Commands](https://asdf-vm.github.io/asdf/#/core-commands)
33+
- [All Plugins](https://asdf-vm.github.io/asdf/#/plugins-all)
34+
- [Create a Plugin](https://asdf-vm.github.io/asdf/#/plugins-create)
35+
36+
## Contributing
37+
38+
See [CONTRIBUTING.md](https://github.com/asdf-vm/asdf/blob/master/CONTRIBUTING.md)

‎docs/_404.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
<h2 align="center">404</h2>
22

3-
<p align="center">
3+
<div style="text-align:center">
4+
45
Woops! It seems we're lost! :sweat_smile:
5-
<br />
6-
Let's <a href="/">go home</a> and try again.
7-
<br />
8-
If we end up lost again, <a href="https://github.com/asdf-vm/asdf/issues/new">yell out for some help</a> :mega:
9-
</p>
10-
11-
<p align="center">
12-
If you are here because of a missing section or translation, please <a href="/#/contributing">think of contributing</a> :two_hearts:
13-
</p>
6+
7+
Let's [go home](/) and try again.
8+
9+
If we end up lost again, [yell out for some help](https://github.com/asdf-vm/asdf/issues/new) :mega:
10+
11+
If you are here because of a missing section or translation, please [think of contributing](contributing-doc-site) :two_hearts:
12+
13+
</div>

‎docs/_coverpage.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,14 @@
11
<!-- ![logo](_media.asdf-vm-logo.svg) -->
22

3-
# asdf vm
3+
# asdf-vm
44

5-
> An extendable version manager
5+
> Manage multiple runtimes with a single CLI tool
6+
7+
<!-- insert asciinema or other gif here -->
68

79
- Bash, Zsh, Fish
8-
- Node.js, Ruby, Python, Elixir ... and more
9-
- Simple plugin system
10+
- Node.js, Ruby, Python, Elixir ... [your favourite language?](plugins-all?id=plugin-list)
11+
- Extend with a simple plugin system
1012

1113
[GitHub](https://github.com/asdf-vm/asdf)
1214
[Get Started](core-manage-asdf-vm)

‎docs/_sidebar.md‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,12 @@
11
<!-- docs/_sidebar.md -->
22

3-
- [Home](/) <!-- ballad of asdf here -->
4-
53
- Core
64

75
- [Manage asdf-vm](core-manage-asdf-vm)
86
- [Manage Plugins](core-manage-plugins)
97
- [Manage Versions](core-manage-versions)
10-
- [Configuration](core-configuration) <!-- tool-versions & .asdfrc & env vars-->
11-
- [All Commands](core-commands) <!-- include uninstall instructions -->
8+
- [Configuration](core-configuration)
9+
- [All Commands](core-commands)
1210

1311
- Plugins
1412

@@ -21,4 +19,4 @@
2119
- [Documentation Site](contributing-doc-site)
2220

2321
- [Changelog](changelog) <!-- pulls in changelog from repo -->
24-
- [Thanks](thanks) <!-- credits, maintainers, contributors -->
22+
- [Thanks](thanks)

‎docs/core-configuration.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
## .tool-versions
22

3-
Whenever `.tool-versions` file is present in a directory, the tool versions it declares will be used in that directory and any subdirectories. **Global defaults can be set in the file `$HOME/.tool-versions`**
3+
Whenever `.tool-versions` file is present in a directory, the tool versions it declares will be used in that directory and any subdirectories.
4+
5+
?> Global defaults can be set in the file `$HOME/.tool-versions`
46

57
This is what a `.tool-versions` file looks like:
68

‎docs/core-manage-asdf-vm.md‎

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -65,11 +65,11 @@ tab will usually do it.)
6565

6666
### Having Issues?
6767

68-
If you're having issues with it not detecting the shims you've installed it's most-likely due to the sourcing of above `asdf.bash` or `asdf.fish` not being at the **BOTTOM** of your `~/.bash_profile`, `~/.zshrc`, or `~/.config/fish/config.fish`. It needs to be sourced **AFTER** you have set your `$PATH.`
68+
!> If you're having issues with it not detecting the shims you've installed it's most-likely due to the sourcing of above `asdf.bash` or `asdf.fish` not being at the **BOTTOM** of your `~/.bash_profile`, `~/.zshrc`, or `~/.config/fish/config.fish`. It needs to be sourced **AFTER** you have set your `$PATH.`
6969

7070
### Plugin Dependencies
7171

72-
For most plugins, it is good if you have installed the following packages OR their equivalent on your OS
72+
?> For most plugins, it is good if you have installed the following packages OR their equivalent on your OS
7373

7474
<!-- tabs:start -->
7575

@@ -78,24 +78,30 @@ For most plugins, it is good if you have installed the following packages OR the
7878
Install these via homebrew:
7979

8080
```shell
81-
coreutils automake autoconf openssl libyaml readline libxslt libtool unixodbc
81+
coreutils automake autoconf openssl \
82+
libyaml readline libxslt libtool unixodbc
8283
```
8384

8485
#### ** Ubuntu **
8586

8687
```shell
87-
automake autoconf libreadline-dev libncurses-dev libssl-dev libyaml-dev libxslt-dev libffi-dev libtool unixodbc-dev
88+
sudo apt install \
89+
automake autoconf libreadline-dev \
90+
libncurses-dev libssl-dev libyaml-dev \
91+
libxslt-dev libffi-dev libtool unixodbc-dev
8892
```
8993

9094
#### **Fedora**
9195

9296
```shell
93-
automake autoconf readline-devel ncurses-devel openssl-devel libyaml-devel libxslt-devel libffi-devel libtool unixODBC-devel
97+
automake autoconf readline-devel \
98+
ncurses-devel openssl-devel libyaml-devel \
99+
libxslt-devel libffi-devel libtool unixODBC-devel
94100
```
95101

96102
<!-- tabs:end -->
97103

98-
**That's all ~! You are ready to use asdf**
104+
That's all! You are ready to use asdf 🎉
99105

100106
## Update
101107

@@ -115,11 +121,13 @@ Uninstalling `asdf` is as simple as:
115121

116122
1. In your `.bashrc` (or `.bash_profile` if you are on OSX) or `.zshrc` find the lines that source `asdf.sh` and the autocompletions. The lines should look something like this:
117123

118-
. $HOME/.asdf/asdf.sh
119-
. $HOME/.asdf/completions/asdf.bash
124+
```shell
125+
. $HOME/.asdf/asdf.sh
126+
. $HOME/.asdf/completions/asdf.bash
127+
```
120128

121129
Remove these lines and save the file.
122130

123131
2. Run `rm -rf ~/.asdf/ ~/.tool-versions` to completely remove all the asdf files from your system.
124132

125-
That's it!
133+
That's it! 🎉

‎docs/core-manage-versions.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ asdf local <name> <version>
3535

3636
See the `.tool-versions` [file in the Configuration section](core-configuration) for details.
3737

38-
Alternatively, if you want to set a version only for the current shell session
38+
?> Alternatively, if you want to set a version only for the current shell session
3939
or for executing just a command under a particular tool version, you
4040
can set an environment variable like `ASDF_${TOOL}_VERSION`.
4141

@@ -74,7 +74,7 @@ The shims themselves are really simple wrappers that `exec` a helper program `as
7474

7575
The `asdf-exec` helper determines the version of tha package to use (as specified in `.tool-versions` file, selected by `asdf local ...` or `asdf global ...`), the final path to the executable in the package installation directory (this can be manipulated by the `exec-path` callback in the plugin) and the environment to execute in (also provided by the plugin - `exec-env` script), and finally it executes it.
7676

77-
Note that because this system uses `exec` calls, any scripts in the package that are meant to be sourced by the shell instead of executed need to be accessed directly instead of via the shim wrapper. The two asdf-vm commands: `which` and `where` can help with this by returning the path to the installed package:
77+
!> Note that because this system uses `exec` calls, any scripts in the package that are meant to be sourced by the shell instead of executed need to be accessed directly instead of via the shim wrapper. The two asdf-vm commands: `which` and `where` can help with this by returning the path to the installed package:
7878

7979
```shell
8080
# returns path to main executable in current version

‎docs/homepage.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<!-- asdf-vm homepage -->
2+
3+
<!-- include the repo readme -->
4+
[](NEW_README.md ":include")
5+
6+
<!-- include the ballad of asdf-vm -->
7+
[](https://raw.githubusercontent.com/asdf-vm/asdf/master/ballad-of-asdf.md ":include")

‎docs/index.html‎

Lines changed: 28 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -10,42 +10,33 @@
1010
content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
1111
/>
1212
<!-- site theme -->
13-
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css" />
14-
<!-- prismjs theme -->
1513
<link
1614
rel="stylesheet"
17-
href="//unpkg.com/prismjs@1.15.0/themes/prism-coy.css"
15+
href="https://unpkg.com/docsify-themeable@0/dist/css/theme-simple.css"
16+
title="light"
1817
/>
18+
<!-- prismjs theme -->
19+
<!-- <link rel="stylesheet" href="//unpkg.com/prismjs@1.15.0/themes/prism.css" /> -->
20+
<!-- <link rel="stylesheet" href="//unpkg.com/prismjs@1.15.0/themes/prism-coy.css" /> -->
21+
<!-- <link rel="stylesheet" href="//unpkg.com/prism-themes/themes/prism-ghcolors.css" /> -->
22+
<!-- <link rel="stylesheet" href="//unpkg.com/prism-themes/themes/prism-atom-dark.css" /> -->
1923
</head>
2024
<body>
21-
<div id="app">asdf-vm loading</div>
25+
<div id="app"></div>
2226
<!-- edit on github plugin must appear here -->
2327
<script src="//unpkg.com/docsify-edit-on-github@1.0.1/index.js"></script>
2428
<script>
2529
window.$docsify = {
2630
name: "asdf-vm",
27-
repo: "asdf-vm/asdf/",
31+
repo: "https://github.com/asdf-vm/asdf",
2832
el: "#app",
33+
homepage: "homepage.md",
2934
coverpage: true,
3035
loadNavbar: true,
3136
loadSidebar: true,
37+
notFoundPage: true,
3238
subMaxLevel: 2,
3339
auto2top: true,
34-
homepage: "https://raw.githubusercontent.com/asdf-vm/asdf/master/README.md",
35-
logo: "/_media/asdf-vm-icon.svg",
36-
coverpage: {
37-
"/": "_coverpage.md",
38-
// "/zh-cn/": "_coverpage.md",
39-
},
40-
nameLink: {
41-
"/": "/",
42-
// "/zh-cn/": "/zh-cn/",
43-
},
44-
notFoundPage: {
45-
"/": "_404.md",
46-
// "/zh-cn": "zh-cn/_404.md",
47-
},
48-
// fallbackLanguages: ["en"],
4940
alias: {
5041
".*?/plugins-all":
5142
"https://raw.githubusercontent.com/asdf-vm/asdf-plugins/master/README.md",
@@ -64,11 +55,9 @@
6455
paths: "auto",
6556
placeholder: {
6657
"/": "Type to search",
67-
// "/zh-cn/": "搜索",
6858
},
6959
noData: {
7060
"/": "No Results",
71-
// "/zh-cn/": "找不到结果",
7261
},
7362
},
7463
plugins: [
@@ -85,9 +74,24 @@
8574
<script src="//unpkg.com/docsify/lib/plugins/emoji.min.js"></script>
8675
<script src="//unpkg.com/docsify/lib/plugins/zoom-image.min.js"></script>
8776
<!-- 3rd party plugins -->
88-
<script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
89-
<script src="//unpkg.com/prismjs/components/prism-markdown.min.js"></script>
77+
<script src="//unpkg.com/docsify-themeable@0"></script>
9078
<script src="//unpkg.com/docsify-copy-code@2"></script>
9179
<script src="//unpkg.com/docsify-tabs@1"></script>
80+
<script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
81+
<script src="//unpkg.com/prismjs/components/prism-markdown.min.js"></script>
82+
<style>
83+
:root {
84+
/* Reduce the font size */
85+
--base-font-size: 14px;
86+
87+
/* Change the theme color hue */
88+
--theme-color: #aa00d4;
89+
90+
/* generate new cover bg color each load */
91+
--cover-background-color: ;
92+
/* leave cover page title black */
93+
--cover-heading-color: ;
94+
}
95+
</style>
9296
</body>
9397
</html>

‎docs/thanks.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ Copyright 2014 to the end of time ([MIT License](https://github.com/asdf-vm/asdf
1010
- [@danhper](https://github.com/danhper)
1111
- [@Stratus3D](https://github.com/Stratus3D)
1212
- [@vic](https://github.com/vic)
13+
- [@jthegedus](https://github.com/jthegedus)
1314

1415
## Contributors
1516

0 commit comments

Comments
 (0)