Skip to content

Commit 35ab035

Browse files
jcubicjcubic
committed
(docs) add getting started guide
1 parent ad1708d commit 35ab035

File tree

1 file changed

+197
-23
lines changed

1 file changed

+197
-23
lines changed

‎docs/docs/intro.md

+197-23
Original file line numberDiff line numberDiff line change
@@ -2,46 +2,220 @@
22
sidebar_position: 1
33
---
44

5-
# Tutorial Intro
5+
# Getting Started
66

7-
Let's discover **Docusaurus in less than 5 minutes**.
7+
## Introduction
88

9-
## Getting Started
9+
jQuery Terminal is a JavaScript library that requires jQuery to work properly. It's a library that
10+
allow you to create terminal based web apps. It's different from
11+
[xterm.js](https://github.com/xtermjs/xterm.js/), because you need to write your whole logic in
12+
client JavaScript code. In comparison, Xterm.js is a library to create a real terminal interface for
13+
a real Linux system on the backend. It allows running a real
14+
[CLI](https://en.wikipedia.org/wiki/Command-line_interface)/[TUI](https://en.wikipedia.org/wiki/Text-based_user_interface)
15+
applications like VI that run on the backend. To have the same in jQuery Terminal you will need to
16+
have a VI implemented in JavaScript. For this you can check [jsvi](https://github.com/jcubic/jsvi).
1017

11-
Get started by **creating a new site**.
1218

13-
Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
19+
To create an app using jQuery Terminal, first, you need to create an HTML page, and then include
20+
jQuery and both the JavaScript and CSS files from jQuery Terminal. You can also use [webpack or other
21+
bundlers](#???). In this tutorial, you will learn all the basics needed to create your own
22+
Terminal on a webpage.
1423

15-
### What you'll need
24+
## jsDelivr CDN
1625

17-
- [Node.js](https://nodejs.org/en/download/) version 18.0 or above:
18-
- When installing Node.js, you are recommended to check all checkboxes related to dependencies.
26+
The best way to get jQuery Terminal is using [jsDelivr](https://www.jsdelivr.com/), it's CDN (Content Delivery Network),
27+
that makes loading static assets (like JavaScript or CSS files) faster.
1928

20-
## Generate a new site
29+
Those are main files that you need to include:
2130

22-
Generate a new Docusaurus site using the **classic template**.
31+
* `https://cdn.jsdelivr.net/npm/[email protected]/js/jquery.terminal.min.js`
32+
* `https://cdn.jsdelivr.net/npm/[email protected]/css/jquery.terminal.min.css`
2333

24-
The classic template will automatically be added to your project after you run the command:
34+
## HTML page
2535

26-
```bash
27-
npm init docusaurus@latest my-website classic
36+
Below is basic HTML code that you need:
37+
38+
```html
39+
<!DOCTYPE html>
40+
<html>
41+
<head>
42+
<script src="https://cdn.jsdelivr.net/npm/jquery"></script>
43+
<script src="https://cdn.jsdelivr.net/npm/jquery.terminal/js/jquery.terminal.min.js"></script>
44+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/jquery.terminal/css/jquery.terminal.min.css" />
45+
</head>
46+
<body>
47+
<scrpt>/* your code here */</script>
48+
</body>
49+
</html>
50+
```
51+
52+
The version `@2.x.x` is optional.
53+
54+
:::note
55+
You can write your code inline like in the code above, or write separate file and use HTML like this:
56+
```html
57+
<script src="your-file.js"></script>
58+
```
59+
:::
60+
61+
## Older browsers
62+
63+
If you need to support older browsers (like IE11) you can also include this JavaScript file:
64+
65+
```html
66+
<script src="https://cdn.jsdelivr.net/npm/js-polyfills/keyboard.js"></script>
67+
```
68+
69+
It's a polyfill for key property on keyboard events. You can see the
70+
[browser support for this feature](https://caniuse.com/keyboardevent-key).
71+
72+
## Chinese and Japanese character support
73+
74+
There are characters like Chinese and Japanese that are wider then 1 character. To display those
75+
characters properly on the terminal you can use [wcwidth](https://github.com/timoxley/wcwidth) libary,
76+
which calculates the width of the characters.
77+
78+
You can add this code to your HTML:
79+
80+
```html
81+
<script src="https://cdn.jsdelivr.net/gh/jcubic/static/js/wcwidth.js"></script>
82+
```
83+
84+
Above file is a collection of libraries converted to [UMD](https://github.com/umdjs/umd) using
85+
browserify.
86+
87+
88+
## Terminal Initialization
89+
90+
To initialize the terminal you need to use code like this:
91+
92+
```javascript
93+
$('body').terminal();
94+
```
95+
96+
Above code is specific to jQuery. If you're not familar with it, it's basically dolar function that accept a CSS selector
97+
that points to element that will be transformed into your terminal. When you use `body` as the selector, it will create
98+
full screen terminal. But you can also use element that is part of your webpage, like a
99+
[window that have a terminal inside](#???).
100+
101+
## Interpreter
102+
103+
The first argument to the terminal is an interpreter, the simplest way to add multiple commands is using an object.
104+
105+
```javascript
106+
$('body').terminal({
107+
hello() {
108+
this.echo('hello, world!');
109+
},
110+
bye() {
111+
this.echo('goodby');
112+
}
113+
});
114+
```
115+
116+
This code will create two commands:
117+
* `hello` which prints on the terminal text `"hello, world!"`,
118+
* `bye` which prints `"goodby"`
119+
120+
To create arguments to the commands you add them as function paramters:
121+
122+
```javascript
123+
$('body').terminal({
124+
hello(what) {
125+
this.echo(`hello, this is ${what}!`);
126+
},
127+
bye() {
128+
this.echo('goodby');
129+
}
130+
});
28131
```
29132

30-
You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
133+
If you type `hello Terminal` it will print "hello, this is Terminal"
134+
135+
## Terminal Options
31136

32-
The command also installs all necessary dependencies you need to run Docusaurus.
137+
### Arity
33138

34-
## Start your site
139+
If you want the argument to be optional you need to `checkArity: false` option (options is
140+
an object that is a second argumnet to the termianal).
35141

36-
Run the development server:
142+
```javascript
143+
$('body').terminal({
144+
hello(what = 'world') {
145+
this.echo(`hello, this is ${what}!`);
146+
},
147+
bye() {
148+
this.echo('goodby');
149+
}
150+
}, {
151+
checkArity: false
152+
});
153+
```
154+
155+
### Greetings
156+
157+
Another usefull option that you want to change is `greetings`, by default it display jQuery Terminal
158+
[ASCII Art](https://en.wikipedia.org/wiki/ASCII_art), but you can change it.
159+
160+
```javascript
161+
$('body').terminal({
162+
hello(what = 'world') {
163+
this.echo(`hello, this is ${what}!`);
164+
},
165+
bye() {
166+
this.echo('goodby');
167+
}
168+
}, {
169+
greetings: 'My Terminal\n',
170+
checkArity: false
171+
});
172+
```
37173

38-
```bash
39-
cd my-website
40-
npm run start
174+
### Prompt
175+
176+
You can also change the prompt, which is the thing before the cursor, when there is no command typed yet.
177+
By default it's a string `'> '`. But you can change it and use different string:
178+
179+
```javascript
180+
$('body').terminal({
181+
hello(what = 'world') {
182+
this.echo(`hello, this is ${what}!`);
183+
},
184+
bye() {
185+
this.echo('goodby');
186+
}
187+
}, {
188+
greetings: 'My Terminal\n',
189+
prompt: '$ ',
190+
checkArity: false
191+
});
41192
```
42193

43-
The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
194+
### Completion
195+
196+
By default when you press `<TAB>` key, the terminal will insert a `TAB` key. You can make it complete the command,
197+
you're typing. When using object as an interpreter (like in above examples) all you have to do is to set an option:
198+
`completion: true`:
199+
200+
```javascript
201+
$('body').terminal({
202+
hello(what = 'world') {
203+
this.echo(`hello, this is ${what}!`);
204+
},
205+
bye() {
206+
this.echo('goodby');
207+
}
208+
}, {
209+
greetings: 'My Terminal\n',
210+
prompt: '$ ',
211+
completion: true,
212+
checkArity: false
213+
});
214+
```
44215

45-
The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
216+
## See also
46217

47-
Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.
218+
* [What you can echo?](#???)
219+
* [Terminal Interpreter](#???)
220+
* [All about completion](#???)
221+
* [Coloring the terminal](#???)

0 commit comments

Comments
 (0)