genanki-js 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/License.md CHANGED
@@ -1,22 +1,22 @@
1
- ### [sql.js](https://github.com/sql-js/sql.js)
2
- [The MIT License](https://github.com/sql-js/sql.js/blob/master/LICENSE)
3
- <br>Copyright (c) 2017 sql.js authors (see AUTHORS)
4
-
5
- ### [JSZip](https://github.com/Stuk/jszip)
6
- JSZip is dual-licensed. You may use it under the MIT license or the GPLv3 license. See [JSZip LICENSE.markdown](https://github.com/Stuk/jszip/blob/master/LICENSE.markdown).
7
-
8
- ### [FileSaver.js](https://github.com/eligrey/FileSaver.js)
9
- [The MIT License](https://github.com/eligrey/FileSaver.js/blob/master/LICENSE.md)
10
- <br>Copyright © 2016 Eli Grey.
11
-
12
- ### [mkanki](https://github.com/nornagon/mkanki)
13
- [GNU Affero General Public License v3](https://opensource.org/licenses/AGPL-3.0)
14
- <br>Copyright (c) 2018 Jeremy Apthorp
15
-
16
- ### [js-sha256](https://github.com/emn178/js-sha256)
17
- [The MIT License](https://github.com/emn178/js-sha256/blob/master/LICENSE.txt)
18
- <br>Copyright (c) Chen, Yi-Cyuan 2017
19
-
20
- ### [genanki](https://github.com/kerrickstaley/genanki)
21
- [The MIT License](https://github.com/kerrickstaley/genanki/blob/master/LICENSE.txt)
22
- <br>Copyright (c) Kerrick Staley 2021
1
+ ### [sql.js](https://github.com/sql-js/sql.js)
2
+ [The MIT License](https://github.com/sql-js/sql.js/blob/master/LICENSE)
3
+ <br>Copyright (c) 2017 sql.js authors (see AUTHORS)
4
+
5
+ ### [JSZip](https://github.com/Stuk/jszip)
6
+ JSZip is dual-licensed. You may use it under the MIT license or the GPLv3 license. See [JSZip LICENSE.markdown](https://github.com/Stuk/jszip/blob/master/LICENSE.markdown).
7
+
8
+ ### [FileSaver.js](https://github.com/eligrey/FileSaver.js)
9
+ [The MIT License](https://github.com/eligrey/FileSaver.js/blob/master/LICENSE.md)
10
+ <br>Copyright © 2016 Eli Grey.
11
+
12
+ ### [mkanki](https://github.com/nornagon/mkanki)
13
+ [GNU Affero General Public License v3](https://opensource.org/licenses/AGPL-3.0)
14
+ <br>Copyright (c) 2018 Jeremy Apthorp
15
+
16
+ ### [js-sha256](https://github.com/emn178/js-sha256)
17
+ [The MIT License](https://github.com/emn178/js-sha256/blob/master/LICENSE.txt)
18
+ <br>Copyright (c) Chen, Yi-Cyuan 2017
19
+
20
+ ### [genanki](https://github.com/kerrickstaley/genanki)
21
+ [The MIT License](https://github.com/kerrickstaley/genanki/blob/master/LICENSE.txt)
22
+ <br>Copyright (c) Kerrick Staley 2021
package/README.md CHANGED
@@ -1,89 +1,179 @@
1
- # genanki-js
2
- A JavaScript implementation for generating Anki decks in browser. This is fork of [mkanki](https://github.com/nornagon/mkanki).
3
-
4
- # QuickStart
5
- ```
6
- npm i genanki-js
7
- ```
8
-
9
- ### View sample project to get started
10
- [genanki-js-template](https://github.com/krmanik/genanki-js/tree/main/sample)
11
-
12
- # Documentation
13
- View [Documentation](https://krmanik.github.io/genanki-js)
14
-
15
- ## CSV/TSV to Anki Package
16
- Visit page and select `CSV to APKG` from top menu.<br>
17
- [CSV to APKG](https://krmanik.github.io/genanki-js/demo/index.html)
18
-
19
- # Set-up a project from scratch
20
- 1. Install genanki-js
21
- ```
22
- npm i genanki-js
23
- ```
24
-
25
- 2. Create a `SQL` global variable (may be added to index.js). Sql setup may be different for different JS library. View for react [sql-js/react-sqljs-demo](https://github.com/sql-js/react-sqljs-demo) and read more at [sql.js.org](https://sql.js.org/)
26
-
27
- ```js
28
- // The `initSqlJs` function is globally provided by all of the main dist files if loaded in the browser.
29
- // We must specify this locateFile function if we are loading a wasm file from anywhere other than the current html page's folder.
30
- config = {
31
- locateFile: filename => `js/sql/sql-wasm.wasm`
32
- }
33
-
34
- let SQL;
35
- initSqlJs(config).then(function (sql) {
36
- //Create the database
37
- SQL = sql;
38
- });
39
- ```
40
-
41
- 3. Now use following `Examples` to generate and export decks.
42
-
43
- *View more examples here [Examples](https://krmanik.github.io/genanki-js/demo/index.html)*
44
-
45
- # Examples
46
- ```js
47
- var m = new Model({
48
- name: "Basic (and reversed card)",
49
- id: "1543634829843",
50
- flds: [
51
- { name: "Front" },
52
- { name: "Back" }
53
- ],
54
- req: [
55
- [ 0, "all", [ 0 ] ],
56
- [ 1, "all", [ 1 ] ]
57
- ],
58
- tmpls: [
59
- {
60
- name: "Card 1",
61
- qfmt: "{{Front}}",
62
- afmt: "{{FrontSide}}\n\n<hr id=answer>\n\n{{Back}}",
63
- },
64
- {
65
- name: "Card 2",
66
- qfmt: "{{Back}}",
67
- afmt: "{{FrontSide}}\n\n<hr id=answer>\n\n{{Front}}",
68
- }
69
- ],
70
- })
71
-
72
- var d = new Deck(1276438724672, "Test Deck")
73
-
74
- d.addNote(m.note(['this is front', 'this is back']))
75
-
76
- var p = new Package()
77
- p.setSqlJs(SQL); // global SQL variable from step 2 in setup
78
- p.addDeck(d)
79
-
80
- p.writeToFile('deck.apkg')
81
- ```
82
-
83
- # License
84
- ### [genanki-js]()
85
- [GNU Affero General Public License v3](https://opensource.org/licenses/AGPL-3.0)
86
- <br>Copyright (c) 2021 Mani
87
-
88
- ## Other Third Party Licenses
89
- [License.md](https://github.com/krmanik/genanki-js/blob/master/License.md)
1
+ # genanki-js
2
+ A JavaScript implementation for generating Anki decks in browser. This is fork of [mkanki](https://github.com/nornagon/mkanki).
3
+
4
+ # QuickStart
5
+ genanki-js can be used from npm (with a bundler such as Vite, or in Node.js), or with a plain `<script>` tag.
6
+
7
+ ## npm
8
+ ```
9
+ npm install genanki-js
10
+ ```
11
+
12
+ ```js
13
+ import { Model, Deck, Package } from "genanki-js"
14
+ // or: const { Model, Deck, Package } = require("genanki-js")
15
+ ```
16
+
17
+ [JSZip](https://github.com/Stuk/jszip) and [sql.js](https://github.com/sql-js/sql.js) are installed as dependencies and loaded automatically, nothing has to be configured. sql.js is only loaded when the first package is generated.
18
+
19
+ - **Browser**: `package.writeToFile('deck.apkg')` downloads the file.
20
+ - **Node.js**: use `package.generate('nodebuffer')` and write the result yourself:
21
+ ```js
22
+ import { writeFile } from "node:fs/promises"
23
+ await writeFile("deck.apkg", await p.generate("nodebuffer"))
24
+ ```
25
+
26
+ <details>
27
+ <summary>esbuild and webpack configuration</summary>
28
+
29
+ sql.js contains `require("node:fs")` and `require("node:crypto")` calls that only run in Node.js. Vite handles this automatically. For esbuild and webpack, mark them as external:
30
+
31
+ ```sh
32
+ esbuild src/main.js --bundle --external:node:*
33
+ ```
34
+
35
+ ```js
36
+ // webpack.config.js
37
+ module.exports = {
38
+ // ...
39
+ externals: { "node:fs": "{}", "node:crypto": "{}" },
40
+ }
41
+ ```
42
+ </details>
43
+
44
+ To use another sql.js build (for example `sql-wasm.js` with your own `locateFile`), pass it with `setSqlJs`:
45
+ ```js
46
+ import initSqlJs from "sql.js"
47
+ import { setSqlJs } from "genanki-js"
48
+
49
+ setSqlJs(await initSqlJs({ locateFile: file => `/assets/${file}` }))
50
+ ```
51
+
52
+ ## Script tag
53
+ Download the [genanki](https://github.com/krmanik/genanki-js/releases) zip file from the release page. The zip file contains two folders
54
+
55
+ - `dist` : This folder contains `genanki.js` file. If project already configured with [sql.js](https://github.com/sql-js/sql.js) and [JSZip](https://github.com/Stuk/jszip) then just add `genanki.js` file to project.
56
+
57
+ - `sample` : This folder contains [sql.js](https://github.com/sql-js/sql.js), [FileSaver.js](https://github.com/eligrey/FileSaver.js), [JSZip](https://github.com/Stuk/jszip) and [genanki.js](https://github.com/krmanik/genanki-js). It is ready to use folder.
58
+
59
+ Alternatively, `genanki.js` can also be loaded from CDN.
60
+ ```html
61
+ <script src="https://cdn.jsdelivr.net/npm/genanki-js@2.1.0/dist/genanki.js"></script>
62
+ ```
63
+
64
+ ### Set up a new project from scratch
65
+ 1. Add [sql.js](https://github.com/sql-js/sql.js) and [JSZip](https://github.com/Stuk/jszip) to the project, then `genanki.js` from the `dist` folder. [FileSaver.js](https://github.com/eligrey/FileSaver.js) is optional, it is used for downloading when available.
66
+
67
+ >*Note: [mkanki](https://github.com/nornagon/mkanki) uses `better-sql`, `fs` and `archiver`, that make it difficult to be used in browser*
68
+
69
+ ```html
70
+ <!-- sqlite, sql-wasm-inline.js from sql.js renamed to sql.js -->
71
+ <script src='js/sql/sql.js'></script>
72
+
73
+ <!-- jszip for .apkg -->
74
+ <script src="js/jszip.min.js"></script>
75
+
76
+ <!-- optional, File saver -->
77
+ <script src="js/filesaver/FileSaver.min.js"></script>
78
+
79
+ <!-- for creating and exporting anki package file -->
80
+ <script src='genanki.js'></script>
81
+ ```
82
+
83
+ 2. genanki.js calls the global `initSqlJs()` when the first package is generated. If sql.js needs a configuration, for example the location of the `.wasm` file, initialize it yourself and pass it to genanki.js
84
+ ```js
85
+ initSqlJs({
86
+ locateFile: filename => `js/sql/${filename}`
87
+ }).then(function (SQL) {
88
+ setSqlJs(SQL);
89
+ });
90
+ ```
91
+
92
+ 3. Now use following `Examples` to generate and export decks.
93
+
94
+ The classes are available as globals (`Model`, `Deck`, `Package`, ...) and in the `genanki` namespace (`genanki.Model`, ...).
95
+
96
+ # Documentation
97
+ View [Documentation](https://krmanik.github.io/genanki-js/#/)
98
+
99
+ *View more examples here [Examples](https://krmanik.github.io/genanki-js/#/examples)*
100
+
101
+ # CSV/TSV to Anki Package
102
+ Visit page and select `CSV to APKG` from top menu.<br>
103
+ [CSV to APKG](https://krmanik.github.io/genanki-js/demo/index.html#)
104
+
105
+ # Examples
106
+ ```js
107
+ var m = new Model({
108
+ name: "Basic (and reversed card)",
109
+ id: "1543634829843",
110
+ flds: [
111
+ { name: "Front" },
112
+ { name: "Back" }
113
+ ],
114
+ req: [
115
+ [ 0, "all", [ 0 ] ],
116
+ [ 1, "all", [ 1 ] ]
117
+ ],
118
+ tmpls: [
119
+ {
120
+ name: "Card 1",
121
+ qfmt: "{{Front}}",
122
+ afmt: "{{FrontSide}}\n\n<hr id=answer>\n\n{{Back}}",
123
+ },
124
+ {
125
+ name: "Card 2",
126
+ qfmt: "{{Back}}",
127
+ afmt: "{{FrontSide}}\n\n<hr id=answer>\n\n{{Front}}",
128
+ }
129
+ ],
130
+ })
131
+
132
+ var d = new Deck(1276438724672, "Test Deck")
133
+
134
+ d.addNote(m.note(['this is front', 'this is back']))
135
+
136
+ var p = new Package()
137
+ p.addDeck(d)
138
+
139
+ p.writeToFile('deck.apkg')
140
+ ```
141
+
142
+ ### Cloze
143
+ ```js
144
+ var m = new ClozeModel({
145
+ name: "Cloze",
146
+ id: "1550428389000",
147
+ flds: [
148
+ { name: "Text" },
149
+ { name: "Back Extra" }
150
+ ],
151
+ tmpl: {
152
+ qfmt: "{{cloze:Text}}",
153
+ afmt: "{{cloze:Text}}<br>{{Back Extra}}",
154
+ },
155
+ })
156
+
157
+ var d = new Deck(1550428389001, "Cloze Deck")
158
+ d.addNote(m.note(['{{c1::Paris}} is the capital of {{c2::France}}', 'Europe']))
159
+
160
+ var p = new Package()
161
+ p.addDeck(d)
162
+ p.writeToFile('cloze-deck.apkg')
163
+ ```
164
+
165
+ # Development
166
+ ```
167
+ npm install
168
+ npm run build # bundle genanki/*.js to dist/ (and the demo and sample folders)
169
+ npm test
170
+ npm run vendor # update sql.js, JSZip and FileSaver in the demo and sample folders
171
+ ```
172
+
173
+ # License
174
+ ### [genanki-js](https://github.com/krmanik/genanki-js)
175
+ [GNU Affero General Public License v3](https://opensource.org/licenses/AGPL-3.0)
176
+ <br>Copyright (c) 2021 Mani
177
+
178
+ ## Other Third Party Licenses
179
+ [License.md](https://github.com/krmanik/genanki-js/blob/main/License.md)