Compare commits

..

150 Commits

Author SHA1 Message Date
Aaron O'Mullan af87dc8d7c Bump version to 0.1.0 2014-04-03 16:19:49 -07:00
Aaron O'Mullan 1699028688 Handle empty repoID and print error, fixes #11 2014-04-03 16:10:47 -07:00
Samy Pessé 55d9bfbf18 Enable use of spacebar for scrolling into book body 2014-04-03 15:53:50 -07:00
Samy Pessé c964b53137 Add keyboard shortcut 's' to toggle sidebar 2014-04-03 15:39:05 -07:00
Samy Pessé 510f7bacb4 Show sidebar by default 2014-04-03 15:29:34 -07:00
Samy Pessé c934238f3d Fix #9: add keyboard navigation using right/left 2014-04-03 15:24:57 -07:00
Samy Pessé ab48959968 Update screenshot preview 2014-04-02 21:25:33 -07:00
Samy Pessé eb6204aa42 Bump version to 0.0.4 2014-04-02 20:26:08 -07:00
Samy Pessé a70439f375 Update app.js build 2014-04-02 20:25:52 -07:00
Samy Pessé a3b562b4e8 Prevent default click action on sharing 2014-04-02 20:24:07 -07:00
Samy Pessé aa4e3abc33 Add sharing links in header 2014-04-02 20:17:46 -07:00
Samy Pessé f24a7fbb6e Fix selection of all buffer when clicking on "Solution" 2014-04-02 19:00:50 -07:00
Samy Pessé f3a49306b1 Use prefix for storage key 2014-04-02 18:57:36 -07:00
Samy Pessé f312472abd Add button to edit current chapter in sidebar 2014-04-02 18:53:58 -07:00
Aaron O'Mullan ecb07468f6 Resolve relative links to GitHub repo, fixes #6
Useful for linking to blobs and other files …
2014-04-02 18:40:53 -07:00
Aaron O'Mullan 8fc09e2e05 Add github link resolution test 2014-04-02 18:40:53 -07:00
Aaron O'Mullan ed7798237a Add GITHUB_LINKS.md fixture
For testing github link resolution
2014-04-02 18:40:52 -07:00
Samy Pessé faf63566df Hide articles in progress bar on mobile 2014-04-02 17:48:35 -07:00
Samy Pessé c88382aea0 Update favicon 2014-04-02 17:01:30 -07:00
Samy Pessé 9ee5f48aef Add meta tag generator 2014-04-02 16:53:28 -07:00
Samy Pessé e1dfe5c0f6 Improve meta tags 2014-04-02 16:48:12 -07:00
Aaron O'Mullan 3adcd77ae4 Merge sections together, fixes #7 2014-04-02 16:40:51 -07:00
Aaron O'Mullan 4bdcfd07a9 Add tests for section merging 2014-04-02 16:40:51 -07:00
Aaron O'Mullan a9967df6eb Add HR_PAGE.md fixture
This is for testing that non exercise sections are merged correctly
together and united with HRs
2014-04-02 16:40:51 -07:00
Samy Pessé 62a2e8f81c Fix #8: Improve page title 2014-04-02 16:38:24 -07:00
Aaron O'Mullan 6bcc2d8cf2 Expose titles in navigation of current nodes 2014-04-02 16:33:31 -07:00
Samy Pessé ad1867e4d8 Add preview on readme 2014-04-02 10:40:47 +02:00
Samy Pessé 445c2327c4 Bump version to 0.0.3 2014-04-02 01:36:03 -07:00
Samy Pessé 7a33881b3b Fix mixpanel tracking 2014-04-02 01:35:41 -07:00
Aaron O'Mullan 417ee789c4 Improve README.md, fix minor typos 2014-04-02 01:34:43 -07:00
Samy Pessé 22c118779c Add preview screenshot 2014-04-02 01:27:54 -07:00
Samy Pessé 53dc206d71 Fix format for exercise 2014-04-02 10:20:44 +02:00
Samy Pessé 3c9d8878df Add informations about exercises format 2014-04-02 01:14:15 -07:00
Samy Pessé 03cbe7b18f Add information about summary format 2014-04-02 01:04:01 -07:00
Samy Pessé 85f4c3be58 Add base information on installation in readme 2014-04-02 00:56:02 -07:00
Samy Pessé eb09f61029 Fix usage of highlight.js 2014-04-01 23:00:22 -07:00
Samy Pessé 2cee253be4 Bump version to 0.0.2 2014-04-01 19:32:55 -07:00
Samy Pessé 25162ceaa2 Fix #5: Add favicon 2014-04-01 19:20:38 -07:00
Samy Pessé 840113a48f Improve design of page content (sections and exercises) 2014-04-01 19:10:15 -07:00
Samy Pessé ddffd02b2e Add border radius to sections and footer navigation button 2014-04-01 18:59:59 -07:00
Samy Pessé 520ea847da Make chapter in progress bar clickable 2014-04-01 18:57:48 -07:00
Samy Pessé e77e3b724e Improve footer navigation 2014-04-01 18:49:20 -07:00
Samy Pessé d313589736 Mark chapter as read after the page is viewed 2014-04-01 18:42:43 -07:00
Samy Pessé 466ceb581c Fix execution when contains && 2014-04-01 18:21:01 -07:00
Samy Pessé 835953d8dd Improve lisibility of text in page 2014-04-01 17:57:20 -07:00
Samy Pessé a69e8ec328 Add highlight.js dependency 2014-04-01 17:39:22 -07:00
Samy Pessé 970107c656 Fix #3: Add syntax highlighting 2014-04-01 17:01:44 -07:00
Samy Pessé 7121b7efe3 Fix #4: Add option for defining description 2014-04-01 16:42:15 -07:00
Samy Pessé d02581a21c Add base analytic using mixpanel 2014-04-01 15:39:28 -07:00
Samy Pessé fd5c2f6706 Fix transition on header 2014-04-01 14:42:04 -07:00
Samy Pessé b93f67c84a Save sidebar state 2014-04-01 13:26:06 -07:00
Aaron O'Mullan 86cf2d9d9d Bump version to 0.0.1 2014-04-01 02:51:16 -07:00
Samy Pessé 1e719cf773 Improve footer navigation on mobile 2014-04-01 02:48:00 -07:00
Samy Pessé c66b37d91c Improve progress bar design 2014-04-01 02:38:19 -07:00
Samy Pessé ca2d499f63 Change style of bottom navigation 2014-04-01 02:36:36 -07:00
Samy Pessé b30132d8c8 Fix link to issues 2014-04-01 02:00:53 -07:00
Samy Pessé 71dee7717d Fix summary display on firefox 2014-04-01 01:58:04 -07:00
Samy Pessé 4d880fc05b Improve animation and display of progress bar 2014-04-01 01:51:18 -07:00
Samy Pessé 7b0d50fc45 Fix position of progress bar 2014-04-01 01:23:17 -07:00
Samy Pessé 256d1ba35a Add progress calcul 2014-04-01 01:21:44 -07:00
Aaron O'Mullan cc340db0fa Add cli command serve
This does a build, then spins up a HTTP server to serve the books
contents
2014-04-01 01:14:56 -07:00
Aaron O'Mullan f776748437 Don't add chapters/articles with null paths to navigation 2014-04-01 00:45:52 -07:00
Aaron O'Mullan bb96433fe3 Adjust summary test for new SUMMARY.md fixture 2014-04-01 00:45:51 -07:00
Aaron O'Mullan 6a63708939 Add tests for null paths in navigation
Unfinished chapters/articles should be put in navigation
2014-04-01 00:45:51 -07:00
Samy Pessé e08b09f3cf Fix execution of code 2014-04-01 00:24:09 -07:00
Samy Pessé b3c865ef58 Add execution of exercise 2014-04-01 00:12:26 -07:00
Aaron O'Mullan 2aebb38e58 Add jsrepl to static assets 2014-03-31 23:47:13 -07:00
Samy Pessé 93a0f52b85 Add base for full optimized markdown github style 2014-03-31 23:35:02 -07:00
Samy Pessé 202355729e Fix font-awesome path 2014-03-31 23:18:10 -07:00
Samy Pessé 70569affc2 Fix overflow on header 2014-03-31 23:06:08 -07:00
Samy Pessé d36dfee40b Mark as disabled articles not yet finished in the summary 2014-03-31 23:02:43 -07:00
Samy Pessé eed1dfb243 Only convert markdown file from the navigation 2014-03-31 22:54:22 -07:00
Samy Pessé aefbfaf057 Move getFiles to fs module 2014-03-31 22:45:45 -07:00
Samy Pessé 0f0128fa49 Show level in summary page 2014-03-31 22:35:59 -07:00
Samy Pessé 8edd5e4b3b Signal and mark progress 2014-03-31 22:27:25 -07:00
Samy Pessé 642a338cb0 Mark levels done in local storage 2014-03-31 19:41:29 -07:00
Aaron O'Mullan 77136705fc Add level attribute in navigation 2014-03-31 19:39:38 -07:00
Aaron O'Mullan b16f6d548c Add tests for level attribute in navigation 2014-03-31 19:39:38 -07:00
Samy Pessé 07c10da91f Add base for handling and storing progress 2014-03-31 19:34:50 -07:00
Aaron O'Mullan 0ad6533f12 Add level attribute to chapters/articles 2014-03-31 19:34:06 -07:00
Aaron O'Mullan 2234026153 Add tests for level attribute to chapters/articles 2014-03-31 19:33:55 -07:00
Aaron O'Mullan a6d18e89df Symlink README.html to index.html for book output 2014-03-31 19:25:14 -07:00
Aaron O'Mullan ec570ca68d Remove extra "q" dependency in package.json 2014-03-31 19:19:52 -07:00
Aaron O'Mullan 6bcd483351 Replace glob with better fstream-ignore
It ignores according to .gitignore and other folders
2014-03-31 19:19:52 -07:00
Samy Pessé 347ae52e67 Fix star and watch count 2014-03-31 19:08:06 -07:00
Samy Pessé 5ff6896ee5 Move all javascript to the bundle 2014-03-31 19:04:26 -07:00
Samy Pessé 68e35758c3 Add base for javascript compilation using requirejs 2014-03-31 19:01:01 -07:00
Aaron O'Mullan 84d703c6f5 Ensure destination dir exists before building 2014-03-31 18:28:51 -07:00
Aaron O'Mullan 138dc1f2de Add target _blank support in renderer for external links 2014-03-31 18:15:05 -07:00
Samy Pessé 1ab31ede81 Fix display of long title in summary 2014-03-31 18:01:35 -07:00
Samy Pessé e0a97f2f4b Improve footer navigation display 2014-03-31 17:49:21 -07:00
Samy Pessé 885e451054 Mark as active current chapter 2014-03-31 17:43:07 -07:00
Aaron O'Mullan a7b8e24e7a Fix tiny typo
In string not code
2014-03-31 17:41:37 -07:00
Aaron O'Mullan abf8c59946 Improve navigation from 1st chapter back to intro
1st chapter’s prev, now links to the intro page
2014-03-31 17:40:57 -07:00
Samy Pessé 91a916e146 Improve navigation on mobile resolutions 2014-03-31 17:38:28 -07:00
Aaron O'Mullan 752b26e963 Fix previous/next chapter navigation 2014-03-31 17:36:01 -07:00
Aaron O'Mullan 45574cf7a5 Add better tests for chapter navigation
Proves previous and next chapter logic is broken
2014-03-31 17:36:01 -07:00
Aaron O'Mullan 4607f406ab Add navigation tests for first page for README of a chapter 2014-03-31 17:36:01 -07:00
Samy Pessé bc5d963c5e Fix title position for small screen 2014-03-31 17:28:40 -07:00
Samy Pessé d85ae0a36e Improve title position with summary open in header 2014-03-31 17:27:14 -07:00
Samy Pessé 9c211ab214 Mark active chapter in summary 2014-03-31 17:25:00 -07:00
Samy Pessé ce3e103024 Add navigation parsed in footer 2014-03-31 17:17:34 -07:00
Samy Pessé 8ecaeb86f9 Improve spacing of navigation links in footer 2014-03-31 17:17:24 -07:00
Samy Pessé 1b00fc9620 Add footer for navigation links 2014-03-31 17:06:40 -07:00
Aaron O'Mullan 39f1ed055e Add parse.navigation module
With tests
2014-03-31 17:06:39 -07:00
Aaron O'Mullan 3f3bade58e Change summary data format
Simplify chapter objects, by making them identical to article objects
besides the .articles attribute
2014-03-31 17:06:39 -07:00
Samy Pessé 0821b10e18 Improve page section design 2014-03-31 16:22:28 -07:00
Samy Pessé 37aaab3bae Remove test.js 2014-03-31 16:08:10 -07:00
Aaron O'Mullan fcdb12f4ca Set size of exercise code editor according to solution
Use the number of lines in solution to set editor’s size
2014-03-31 15:55:06 -07:00
Aaron O'Mullan 2d29121e2e Add lex sub-command to gitbook binary
The lex command is useful for debugging files and seeing how they are
parsed
2014-03-31 15:54:26 -07:00
Aaron O'Mullan 36b961c539 Clean output folder before generating 2014-03-31 15:24:38 -07:00
Aaron O'Mullan e9e94a7344 Filter out empty sections when generating pages 2014-03-31 15:14:31 -07:00
Aaron O'Mullan a8e0de86e9 Generate a unique Id for each section 2014-03-31 15:03:06 -07:00
Samy Pessé 6261d42b95 Add base for full display of exercises 2014-03-31 15:01:02 -07:00
Aaron O'Mullan 8e22d80c7c Add content & code generation for exercise sections 2014-03-31 15:00:03 -07:00
Samy Pessé 82b99189b1 Add base display of exercise 2014-03-31 13:59:51 -07:00
Aaron O'Mullan 3f7f5667e4 Merge pull request #1 from GitbookIO/feature/cli
Initial gitbook binary
2014-03-31 13:52:41 -07:00
Aaron O'Mullan a88ea48206 Initial gitbook binary 2014-03-31 13:51:31 -07:00
Samy Pessé c3a181a50d Fix author link 2014-03-31 12:59:26 -07:00
Samy Pessé 0fdd31dc39 Fix link for watcher and stargazers 2014-03-31 12:54:53 -07:00
Samy Pessé d44fd91181 Get watcher and stargazer count using github api 2014-03-31 12:51:27 -07:00
Aaron O'Mullan 264a506e8b Fix bug with exercise classification 2014-03-31 12:40:53 -07:00
Samy Pessé d98669958d Fix header link and display 2014-03-31 12:39:16 -07:00
Samy Pessé 4210794de6 Fix all relative links 2014-03-31 12:31:01 -07:00
Samy Pessé 77a4c1042c Merge branch 'master' of https://github.com/GitbookIO/gitbook 2014-03-31 12:16:16 -07:00
Samy Pessé 6df59745b1 Fix link in summary (absolute to relative) 2014-03-31 12:15:45 -07:00
Samy Pessé 0b08663b70 Fix font path 2014-03-31 12:14:40 -07:00
Samy Pessé 19a3981475 Copy assets to build 2014-03-31 12:10:26 -07:00
Aaron O'Mullan 89593f46ab Normalize .md links to .html when rendering pages 2014-03-31 12:09:28 -07:00
Samy Pessé 1f3f062841 Add base for generation 2014-03-31 12:00:22 -07:00
Aaron O'Mullan 1d321207b0 Normalize chapter & article paths 2014-03-31 12:00:13 -07:00
Aaron O'Mullan bd7531f3cc Add tests for path normalization
.md to .html
2014-03-31 11:58:31 -07:00
Aaron O'Mullan 75073d47a2 Add link to PAGE.md fixture 2014-03-31 11:57:16 -07:00
Aaron O'Mullan 0af1886358 Move summary & page parsing code to lib/parse/ 2014-03-31 01:50:21 -07:00
Aaron O'Mullan d18da55a18 Improve section classification 2014-03-31 01:34:37 -07:00
Aaron O'Mullan 7ab78b420a Change lib entry point to lib/index.js 2014-03-31 01:02:35 -07:00
Aaron O'Mullan 5e183f24de Expose page module in index.js 2014-03-30 22:52:27 -07:00
Aaron O'Mullan 2c36a21938 Render normal sections' content to HTML 2014-03-30 22:51:30 -07:00
Aaron O'Mullan 7b4974209b Add tests for page content rendering 2014-03-30 22:51:02 -07:00
Aaron O'Mullan c21303c762 Add section type detection 2014-03-30 22:36:22 -07:00
Aaron O'Mullan 4c1435f27f Test for section types 2014-03-30 22:36:08 -07:00
Aaron O'Mullan 0199e56000 Add initial page parsing
(Split sections)
2014-03-30 22:30:45 -07:00
Aaron O'Mullan 9284eb4115 Add basic page tests 2014-03-30 22:30:30 -07:00
Aaron O'Mullan cfbdadd6e4 Add title and path parsing for chapters & articles 2014-03-30 22:02:07 -07:00
Aaron O'Mullan 603870ee07 Add test for titles & paths 2014-03-30 22:01:37 -07:00
Aaron O'Mullan 39a80421fc Add summary parsing 2014-03-30 21:30:33 -07:00
Aaron O'Mullan 1d28ab441a Add tests for summary parsing 2014-03-30 21:30:21 -07:00
Aaron O'Mullan d5070c0bf1 Add base dependencies 2014-03-30 20:13:47 -07:00
Aaron O'Mullan 71e9d7bd80 Initial package.json 2014-03-30 20:10:04 -07:00
Aaron O'Mullan 0a104b1f85 Initial commit 2014-03-30 20:01:56 -07:00
654 changed files with 31007 additions and 34582 deletions
-8
View File
@@ -1,8 +0,0 @@
# Changesets
Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
with multi-package repos, or single-package repos to help you version and publish your code. You can
find the full documentation for it [in our repository](https://github.com/changesets/changesets)
We have a quick list of common questions to get you started engaging with this project in
[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Avoid multiple <h1> in the page by using a <div> for the title in the header
-6
View File
@@ -1,6 +0,0 @@
---
'@gitbook/react-openapi': patch
'gitbook': patch
---
Adds content-visibility css property to OpenAPI Operation for better render performance
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/cache-do': minor
---
Experiment with optimizing billable duration in Cloudflare by using multiple RPC sessions instead of one
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Fix scroll position when navigating pages on mobile
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/react-openapi': minor
---
Add Python support in Code Samples
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Add automatic color contrast in site header, restyle search button
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
RND-3532: drop down menu for hidden links at small screen size
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Change dark mode shadow for multi-space search toolbar
-11
View File
@@ -1,11 +0,0 @@
{
"$schema": "https://unpkg.com/@changesets/config@3.0.2/schema.json",
"changelog": "@changesets/cli/changelog",
"commit": false,
"fixed": [],
"linked": [],
"access": "public",
"baseBranch": "main",
"updateInternalDependencies": "patch",
"ignore": []
}
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Use ellipsis and fix icon color for more links in the header on small screen
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Improve consistency of change request preview by removing cache-control on response
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/icons': patch
---
Update version for static assets to fix invalid caching
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Revalidate change request cached content when pressing refresh button
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/icons': patch
---
Fix first run of the package in development mode
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Add navigation tabs for sections
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Improve performances of loading pages with embeds by caching them
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/react-openapi': patch
---
bump: scalar from 1.0.5 to 1.0.7
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Support resolution of new site URLs with sections
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Replace all icons, previously imported from Geist, by new package `@gitbook/icons`
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/cache-do': minor
---
First version of a new cache backend powered by Cloudflare Durable Objects
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Add support for Norwegian language
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Optimize layout shift while transitioning between pages with full width blocks (ex: OpenAPI blocks)
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Add support for page icons
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Fix GitBook specific static assets not being served correctly when deployed on Cloudflare
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Only display spaces dropdown in compact header when site is multi-variants
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Improve perception of fast loading by not rendering skeletons for individual blocks in the top part of the viewport
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/cache-do': patch
---
Enable Workers observability with a sampling of 0.1
-6
View File
@@ -1,6 +0,0 @@
---
'@gitbook/react-openapi': minor
'gitbook': minor
---
Allow selection of server url
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/icons': minor
---
Initial release for `@gitbook/icons`, a package of content icons to be used for pages, documents, etc.
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Automatically scroll to active item in TOC
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Add support for searching results in a sections site
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Persist state of tabs and dynamically sync them based on title
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Ensure "Sponsored via GitBook" can be translated in all languages
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Update ogimage with new design
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Show the caption for file blocks
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Use url hash to open Expandable and scroll to anchor
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Fix margin for paragraphs in quote blocks
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Use new cache backend, powered by Durable Objects, alongside the existing ones (KV, etc).
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Include offset in calculations of whether scrollable element is in view
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/react-openapi': minor
---
Add required query parameters to the code sample
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/react-openapi': minor
---
Display pattern if available in parmas in OpenAPI block
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Fix inconsistent click area in table because of scroll indicator
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Stop using KV cache backend for now, but also improves it for higher performances
-6
View File
@@ -1,6 +0,0 @@
---
'@gitbook/react-openapi': minor
'gitbook': patch
---
Synchronize response and response example tabs
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Show definition title when visible in cards
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Fix flickering when displaying an "Ask" answer with code blocks
-6
View File
@@ -1,6 +0,0 @@
---
'@gitbook/react-openapi': minor
'gitbook': patch
---
Rollback of scalar modal while fixing perf issue
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Optimize images rendered in community ads
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Update design of Checkbox to be more consistent and readable
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/react-contentkit': patch
---
Fix rendering of webframe with SSR causing wrong communication between frame and renderer
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Disable KV cache for docs.gitbook.com as a test, also disable it for change-request to improve consistency
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Add optional env `GITBOOK_INTEGRATIONS_HOST` to configure the host serving the integrations
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/react-openapi': patch
---
Fix crash when `example` is undefined for a response
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Improve the toolbar for change-requests and revisions to show more actions
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Added support for new Reusable Content block.
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Add support for icons style customization for sites
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/react-openapi': patch
---
Adds tabs to Response Example section e.g. for status code examples
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/react-openapi': patch
---
Render mandatory headers in code sample
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/react-openapi': patch
---
Update Scalar client to latest version
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Prevent search indexation for pages where it's configured as disabled
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Fix table of contents being visible on mobile when disabled at the page level
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Fix accessibility of the table of contents by using `aria-current` instead of `aria-selected`
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Update rendering of community ads to match new API response, and make it possible to preview ads.
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/react-math': minor
---
Export binary `gitbook-math` to copy assets to a directory
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Fix "ip" being passed to BSA for community ads
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Improving the look and feel of new section tabs
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Changed the alternative URL resolution criteria in order to support site URLs without /v/ prefix
-5
View File
@@ -1,5 +0,0 @@
---
'@gitbook/icons': minor
---
Fix bin gitbook-icons when installed without the Pro token
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': patch
---
Don't show hidden pages in the empty state of a page
-5
View File
@@ -1,5 +0,0 @@
---
'gitbook': minor
---
Fix linking to a tab itself
-88
View File
@@ -1,88 +0,0 @@
# Welcome to GitBook's contributing guide!
> _For help, support, feature requests, and product questions - head to our [GitHub Community](https://github.com/orgs/GitbookIO/discussions) 🤖_
Thank you for investing your time in contributing to GitBook. Any contribution you make will be reviewed by our team. In this guide, you'll learn the different ways you can contribute.
## Types of Contributions
This repository contains code related to the rendering engine of GitBook's published content. Depending on what you'd like to contribute to, head to the section below to find the necessary steps.
### Add a feature
Because this portion of GitBook is open source and available for you to use - if you think you can provide extra value through a new feature - you're welcome to add it! If you plan to distribute the code, keep the source code public to comply with GNU GPLv3. To clone in a private repository, you must first acquire a [commercial license](https://www.gitbook.com/pricing).
### Create a new issue
If you spot a problem within a repository, [search if an issue already exists](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments). If a related issue doesn't exist, you can open a new issue here!Please make sure any added issues are
- Descriptive
- Thoughtful
- Organized
We recommend adding as many relevant links, minimal reproductions of the issue, and other materials that will help our team solve the issue fast.
### Solve an issue
If you're interested in solving an issue in our repository, start by scanning through it's exisiting issues to find one that you're interested in working on. If you find an issue to work on, you are welcome to open a PR with a fix. See the following sections below for more information on contributing for specific sections.
### Documentation
The official documentation on GitBook open can be found directly in this Readme. Any updates or changes you would like to make, you can make directly to the README of this repository.
## Contributing
### Make changes locally
Any contribution you make can be made to the code located in this repository. In order to contribute, you'll need to start off of a local version of this repository.
#### 1. Fork the repository
##### Using GitHub Desktop:
- [Getting started with GitHub Desktop](https://docs.github.com/en/desktop/installing-and-configuring-github-desktop/getting-started-with-github-desktop) will guide you through setting up Desktop.
- Once Desktop is set up, you can use it to [fork the repo](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/cloning-and-forking-repositories-from-github-desktop)!
##### Using the command line:
- [Fork the repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo#fork-an-example-repository) so that you can make your changes without affecting the original project until you're ready to merge them.
#### 2. Create a working branch and start with your changes
After forking this repository, you'll want to [create a branch](https://docs.github.com/en/issues/tracking-your-work-with-issues/creating-a-branch-for-an-issue) to work off of.
#### 3. Install dependencies and run the project locally
GitBook uses [Bun](https://bun.sh/) to run the project. Make sure you're using the specified version of `node` before running any of the development commands to ensure a smooth development experience.
You can easily do this by running the command `nvm use`.
To start your local version of GitBook, run the command `bun dev`.
#### 4. Preview your changes
When running the development server, published GitBook sites can be rendered through your local version at `http://localhost:3000/`.
For example, our published docs can be viewed using the local version by visiting `http://localhost:3000/docs.gitbook.com` after running the development server.
You can visit any published GitBook site behind your development server. Please make sure your site is [published publicly](https://docs.gitbook.com/published-documentation/publish-your-content-as-a-docs-site) to ensure you can view the site correctly in your development version.
### Commit your update
[Commit your changes](https://github.com/git-guides/git-commit) once you are happy with them. See [Atom's contributing guide](https://github.com/atom/atom/blob/master/CONTRIBUTING.md#git-commit-messages) to know how to use emoji for commit messages!
Once your changes are ready, don't forget to self-review your code to double check that your chagnes are ready to be added.
### Pull Request
When you're finished with the changes, [create a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request), also known as a PR.
- Don't forget to [link PR to issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) if you are solving one.
- Enable the checkbox to [allow maintainer edits](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/allowing-changes-to-a-pull-request-branch-created-from-a-fork) so the branch can be updated for a merge. Once you submit your PR, a GitBook team member will review your proposal. We may ask questions or request for additional information.
- We may ask for changes to be made before a PR can be merged, either using [suggested changes](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/incorporating-feedback-in-your-pull-request) or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.
- As you update your PR and apply changes, mark each conversation as [resolved](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/commenting-on-a-pull-request#resolving-conversations).
- If you run into any merge issues, checkout this [git tutorial](https://lab.github.com/githubtraining/managing-merge-conflicts) to help you resolve merge conflicts and other issues.
### Your PR is merged
Congratulations 🎉 Thank you for your contribution! Once your PR is merged, your contributions will be publicly visible on the relevant repository.
-18
View File
@@ -1,18 +0,0 @@
---
name: Bug report
about: Something not working as expected? Let us look into it
labels: bug
---
## Bug description
_Please describe._
_If this affects the front-end, screenshots would be of great help._
## How to reproduce
1.
2.
3.
## Additional context
@@ -1,37 +0,0 @@
name: 'Setup Playwright'
description: 'Install Playwright and dependencies'
runs:
using: 'composite'
steps:
# Run npm ci and get Playwright version
- name: 🏗 Prepare Playwright env
shell: bash
run: |
PLAYWRIGHT_VERSION=$(npm ls --json @playwright/test | jq --raw-output '.dependencies["gitbook"].dependencies["@playwright/test"].version')
echo "PLAYWRIGHT_VERSION=$PLAYWRIGHT_VERSION" >> $GITHUB_ENV
# Cache browser binaries, cache key is based on Playwright version and OS
- name: 🧰 Cache Playwright browser binaries
uses: actions/cache@v3
id: playwright-cache
with:
path: '~/.cache/ms-playwright'
key: '${{ runner.os }}-playwright-${{ env.PLAYWRIGHT_VERSION }}'
restore-keys: |
${{ runner.os }}-playwright-
# Install browser binaries & OS dependencies if cache missed
- name: 🏗 Install Playwright browser binaries & OS dependencies
if: steps.playwright-cache.outputs.cache-hit != 'true'
shell: bash
working-directory: packages/gitbook
run: |
bun x playwright install --with-deps chromium
# Install only the OS dependencies if cache hit
- name: 🏗 Install Playwright OS dependencies
if: steps.playwright-cache.outputs.cache-hit == 'true'
shell: bash
working-directory: packages/gitbook
run: |
bun x playwright install-deps
-199
View File
@@ -1,199 +0,0 @@
name: CI
on:
pull_request:
push:
branches:
- main
env:
NPMRC_FONT_AWESOME_TOKEN: ${{ secrets.NPMRC_FONT_AWESOME_TOKEN }}
jobs:
deploy:
name: Deploy to Cloudflare Pages
runs-on: ubuntu-latest
permissions:
contents: read
deployments: write
outputs:
deployment_url: ${{ steps.cloudflare.outputs.url }}
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup bun
uses: oven-sh/setup-bun@v1
with:
bun-version: 1.1.18
- name: Install dependencies
run: bun install --frozen-lockfile
env:
PUPPETEER_SKIP_DOWNLOAD: 1
- name: Cache Next.js build
uses: actions/cache@v3
with:
path: |
${{ github.workspace }}/.next/cache
# Generate a new cache whenever packages or source files change.
key: ${{ runner.os }}-nextjs-${{ hashFiles('**/bun.lockb') }}-${{ hashFiles('**/*.js', '**/*.jsx', '**/*.ts', '**/*.tsx') }}
# If source files changed but packages didn't, rebuild from a prior cache.
restore-keys: |
${{ runner.os }}-nextjs-${{ hashFiles('**/bun.lockb') }}-
- name: Sets env vars for production
run: |
echo "SENTRY_ENVIRONMENT=production" >> $GITHUB_ENV
echo "GITBOOK_ASSETS_PREFIX=https://static.gitbook.com" >> $GITHUB_ENV
if: startsWith(github.ref, 'refs/heads/main')
- name: Sets env vars for preview
run: |
echo "SENTRY_ENVIRONMENT=preview" >> $GITHUB_ENV
if: 1 && !startsWith(github.ref, 'refs/heads/main')
- name: Build Next.js with next-on-pages
run: bun run build:cloudflare
env:
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
SENTRY_ORG: ${{ vars.SENTRY_ORG }}
SENTRY_PROJECT: ${{ vars.SENTRY_PROJECT }}
SENTRY_DSN: ${{ vars.SENTRY_DSN }}
- id: cloudflare
name: Publish to Cloudflare Pages
uses: cloudflare/pages-action@v1
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
projectName: ${{ vars.CLOUDFLARE_PROJECT_NAME }}
directory: ./packages/gitbook/.vercel/output/static
gitHubToken: ${{ secrets.GITHUB_TOKEN }}
workingDirectory: ./
- name: Outputs
run: |
echo "ID: ${{ steps.cloudflare.outputs.id }}"
echo "URL: ${{ steps.cloudflare.outputs.url }}"
echo "Environment: ${{ steps.cloudflare.outputs.environment }}"
echo "Alias: ${{ steps.cloudflare.outputs.alias }}"
- name: Archive build output
uses: actions/upload-artifact@v4
with:
name: build-output
path: .vercel/
visual-testing:
runs-on: ubuntu-latest
name: Visual Testing
needs: deploy
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup bun
uses: oven-sh/setup-bun@v1
with:
bun-version: 1.1.18
- name: Install dependencies
run: bun install --frozen-lockfile
- name: Setup Playwright
uses: ./.github/actions/setup-playwright
- name: Run Playwright tests
run: bun e2e
env:
BASE_URL: ${{needs.deploy.outputs.deployment_url}}
ARGOS_TOKEN: ${{ secrets.ARGOS_TOKEN }}
- uses: actions/upload-artifact@v4
if: ${{ !cancelled() }}
with:
name: playwright-test-results
path: packages/gitbook/test-results/
retention-days: 3
pagespeed-testing:
runs-on: ubuntu-latest
name: PageSpeed Testing
needs: deploy
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup bun
uses: oven-sh/setup-bun@v1
with:
bun-version: 1.1.18
- name: Install dependencies
run: bun install --frozen-lockfile
env:
PUPPETEER_SKIP_DOWNLOAD: 1
- name: Run pagespeed tests
run: bun ./packages/gitbook/tests/pagespeed-testing.ts $DEPLOYMENT_URL
env:
DEPLOYMENT_URL: ${{needs.deploy.outputs.deployment_url}}
PAGESPEED_API_KEY: ${{ secrets.PAGESPEED_API_KEY }}
format:
runs-on: ubuntu-latest
name: Format
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup bun
uses: oven-sh/setup-bun@v1
with:
bun-version: 1.1.18
- name: Install dependencies
run: bun install --frozen-lockfile
env:
PUPPETEER_SKIP_DOWNLOAD: 1
- run: bun format:check
lint:
runs-on: ubuntu-latest
name: Lint
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup bun
uses: oven-sh/setup-bun@v1
with:
bun-version: 1.1.18
- name: Install dependencies
run: bun install --frozen-lockfile
env:
PUPPETEER_SKIP_DOWNLOAD: 1
- run: bun lint --no-cache
test:
runs-on: ubuntu-latest
name: Test
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup bun
uses: oven-sh/setup-bun@v1
with:
bun-version: 1.1.18
- name: Install dependencies
run: bun install --frozen-lockfile
env:
PUPPETEER_SKIP_DOWNLOAD: 1
- run: bun unit
build-oss:
# CI to check that the repository builds correctly on a machine without the credentials
runs-on: ubuntu-latest
name: Build (Open Source)
env:
NPMRC_FONT_AWESOME_TOKEN: ''
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup bun
uses: oven-sh/setup-bun@v1
with:
bun-version: 1.1.18
- name: Install dependencies
run: bun install --frozen-lockfile
env:
PUPPETEER_SKIP_DOWNLOAD: 1
- run: bun run build
typecheck:
runs-on: ubuntu-latest
name: Typecheck
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup bun
uses: oven-sh/setup-bun@v1
with:
bun-version: 1.1.18
- name: Install dependencies
run: bun install --frozen-lockfile
env:
PUPPETEER_SKIP_DOWNLOAD: 1
- run: bun typecheck
-60
View File
@@ -1,60 +0,0 @@
name: Publish
on:
push:
branches:
- main
concurrency: ${{ github.workflow }}-${{ github.ref }}
jobs:
publish:
name: Publish
runs-on: ubuntu-latest
steps:
- name: Checkout Repo
uses: actions/checkout@v3
with:
# This makes Actions fetch all Git history so that Changesets can generate changelogs with the correct commits
fetch-depth: 0
- name: Setup bun
uses: oven-sh/setup-bun@v1
with:
bun-version: 1.1.18
- name: Install dependencies
run: bun install --frozen-lockfile
env:
PUPPETEER_SKIP_DOWNLOAD: 1
- name: Create Release Pull Request or Publish to npm
id: changesets
uses: changesets/action@v1
with:
publish: npm run release
env:
# Using a PAT instead of GITHUB_TOKEN because we need to run workflows when releases are created
# https://github.com/orgs/community/discussions/26875#discussioncomment-3253761
GITHUB_TOKEN: ${{ secrets.GH_PERSONAL_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
release-preview:
# For now it releases the cache-do to both preview and production
# Once we changed to deploy the app only on release, we should change `release:preview` in `cache-do`
name: Release Preview
runs-on: ubuntu-latest
steps:
- name: Checkout Repo
uses: actions/checkout@v3
- name: Setup bun
uses: oven-sh/setup-bun@v1
with:
bun-version: 1.1.18
- name: Install dependencies
run: bun install --frozen-lockfile
env:
PUPPETEER_SKIP_DOWNLOAD: 1
- name: Release preview packages
run: bun run release:preview
env:
CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+23 -22
View File
@@ -1,24 +1,25 @@
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
# Logs
logs
*.log
# dependencies
# Runtime data
pids
*.pid
*.seed
# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov
# Coverage directory used by tools like istanbul
coverage
# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
.grunt
# Compiled binary addons (http://nodejs.org/api/addons.html)
build/Release
# Dependency directory
# Deployed apps should consider commenting this line out:
# see https://npmjs.org/doc/faq.html#Should-I-check-my-node_modules-folder-into-git
node_modules
/.pnp
.pnp.js
# misc
.DS_Store
*.pem
# debug
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# Turbo
.turbo
# Vercel
.vercel
# Env files
.env.local
-1
View File
@@ -1 +0,0 @@
v20.6
-10
View File
@@ -1,10 +0,0 @@
.next
.vercel
# Generated
packages/emoji-codepoints/index.ts
packages/gitbook/public/~gitbook/static/
packages/icons/src/data/*.json
# Build files
dist/
-5
View File
@@ -1,5 +0,0 @@
{
"printWidth": 100,
"singleQuote": true,
"tabWidth": 4
}
-11
View File
@@ -1,11 +0,0 @@
{
"tailwindCSS.experimental.classRegex": [
["Style \\=([^;]*);", "'([^']*)'"],
["Style \\=([^;]*);", "\"([^\"]*)\""],
["Style \\=([^;]*);", "\\`([^\\`]*)\\`"],
["style \\=([^;]*);", "'([^']*)'"],
["style \\=([^;]*);", "\"([^\"]*)\""],
["style \\=([^;]*);", "\\`([^\\`]*)\\`"]
],
"tailwindCSS.classAttributes": ["class", "className", "style", ".*Style"]
}
+63
View File
@@ -0,0 +1,63 @@
module.exports = function (grunt) {
var path = require("path");
// Load NPM tasks
grunt.loadNpmTasks('grunt-contrib-less');
grunt.loadNpmTasks('grunt-contrib-requirejs');
// Init GRUNT configuraton
grunt.initConfig({
pkg: grunt.file.readJSON('package.json'),
less: {
development: {
options: {
compress: true,
yuicompress: true,
optimization: 2
},
files: {
"assets/static/style.css": "assets/stylesheets/main.less"
}
}
},
requirejs: {
compile: {
options: {
name: "app",
baseUrl: "assets/javascript/",
out: "assets/static/app.js",
preserveLicenseComments: false,
optimize: "uglify",
include: ["requireLib"],
paths: {
"jQuery": 'vendors/jquery',
"lodash": 'vendors/lodash',
"requireLib": 'vendors/require',
"Mousetrap": 'vendors/mousetrap'
},
shim: {
'jQuery': {
exports: '$'
},
'lodash': {
exports: '_'
},
'Mousetrap': {
exports: 'Mousetrap'
}
}
}
}
}
});
// Build
grunt.registerTask('build', [
'less',
'requirejs'
]);
grunt.registerTask('default', [
'build'
]);
};
+201 -674
View File
@@ -1,674 +1,201 @@
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users. We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors. You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so. This is fundamentally incompatible with the aim of
protecting users' freedom to change the software. The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable. Therefore, we
have designed this version of the GPL to prohibit the practice for those
products. If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary. To prevent this, the GPL assures that
patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year> <name of author>
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
<program> Copyright (C) <year> <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, your program's commands
might be different; for a GUI interface, you would use an "about box".
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
<https://www.gnu.org/licenses/>.
The GNU General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library, you
may consider it more useful to permit linking proprietary applications with
the library. If this is what you want to do, use the GNU Lesser General
Public License instead of this License. But first, please read
<https://www.gnu.org/licenses/why-not-lgpl.html>.
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "{}"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright {yyyy} {name of copyright owner}
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
+66 -132
View File
@@ -1,159 +1,93 @@
<h1 align="center">GitBook</h1>
GitBook
=======
<p align="center">
<a href="https://docs.gitbook.com/">Docs</a> - <a href="https://github.com/GitbookIO/community">Community</a> - <a href="https://developer.gitbook.com/">Developer Docs</a> - <a href="https://changelog.gitbook.com/">Changelog</a> - <a href="https://github.com/GitbookIO/gitbook/issues/new?assignees=&labels=bug&template=bug_report.md">Bug reports</a>
</p>
GiBook is a command line tool (and Node.js library) for building beautiful programming books and exercises using GitHub/Git and Markdown. You can see an example: [Learn Javascript](http://gitbookio.github.io/javascript/).
<p align="center">
<a href="https://gitbook.com"><img src="https://img.shields.io/static/v1?message=Documented%20on%20GitBook&logo=gitbook&logoColor=ffffff&label=%20&labelColor=5c5c5c&color=3F89A1"></a>
<a href="#"><img src="https://img.shields.io/badge/Open_Source-❤️-FDA599?"/></a>
<a href="/LICENSE"><img src="https://img.shields.io/badge/License-GNU_GPLv3-F4E28D"/></a>
<a href="/.github/CONTRIBUTING.md"><img src="https://img.shields.io/github/contributors/gitbookIO/gitbook"/></a>
<a href="https://github.com/gitbookIO/gitbook/issues"><img src="https://img.shields.io/github/issues/gitbookIO/gitbook"/></a>
</p>
![Image](https://raw.github.com/GitbookIO/gitbook/master/preview.png)
<p align="center">Welcome to GitBook, the platform for managing technical knowledge for teams.</p>
## How to use it:
<p align="center">This repository contains the open source code used to render GitBook's published content.</p>
<p align="center">
<img alt="GitBook Open Published Site" src="./assets/published-site.png">
</p>
## Table of Contents
- [Getting Started](#getting-started)
- [Contributing](#contributing)
- [Types of contributions](#types-of-contributions)
- [Licensing](#license)
- [Acknowledgements](#acknowledgements)
- [Legacy GitBook](#legacy-gitbook-deprecated)
## Getting Started
To run a local version of this project, please follow these simple steps.
### Prerequisites
- Node.js (Version: >=18.x)
- Bun
### Set up
1. Clone the repo into a **public** GitHub repository. If you plan to distribute the code, keep the source code public to comply with GNU GPLv3. To clone in a private repository, acquire a [commercial license](https://www.gitbook.com/pricing).
GitBook can be installed from **NPM** using:
```
git clone https://github.com/gitbookIO/gitbook.git
$ npm install gitbook -g
```
2. Ensure you are using the project's version of `node`. Running `nvm use` will change your local version to the correct one.
3. Install the project's dependencies through Bun.
You can serve a repository as a book using:
```
bun install
$ gitbook serve ./repository
```
4. Start your local development server.
Or simply build the static website using:
```
bun dev
$ gitbook build ./repository --output=./outputFolder
```
5. Open a published GitBook space in your web browser, prefixing it with `http://localhost:3000/`.
Options for commands `build` and `serve` are:
examples:
- http://localhost:3000/docs.gitbook.com
- http://localhost:3000/open-source.gitbook.io/midjourney
Any published GitBook site can be accessed through your local development instance, and any updates you make to the codebase will be reflected in your browser.
### Other development commands
- `bun format`: format the code
- `bun lint`: lint the code
### CI and testing
All pull-requests will be tested against both visual and performances testing to prevent regressions.
## Contributing
GitBook's rendering engine is fully open source and built on top of [Next.js](https://nextjs.org/). Head to our [contributing guide](https://github.com/GitbookIO/gitbook/blob/main/.github/CONTRIBUTING.md) to learn more about the workflow on adding your first Pull Request.
### Types of contributions
We encourage you to contribute to GitBook to help us build the best tool for documenting technical knowledge. If you're looking for some quick ways to contribute, continue reading to learn more about popular contributions.
#### Translations
The GitBook UI is rendered using a set of translation files found in [`packages/gitbook/src/intl/translations`](/packages/gitbook/src/intl/translations/). We welcome all additional translations for the UI.
#### Bugs
Encounter a bug or find an issue you'd like to fix? Helping us fix issues related to GitBook greatly improves the experience for everyone. Head to the issues section of this repository to learn more about the types of bugs you can already help out with.
## Deployment
> [!WARNING]
> While it is possible to self-host this project, we do not recommend this unless you are certain this option fits your need.
>
> _Looking to add a specific feature in GitBook? Head to our [contributing guide](https://github.com/GitbookIO/gitbook/blob/main/.github/CONTRIBUTING.md) to get started._
>
> Self-hosting this project puts the responsibility of maintaining and merging future updates on **you**. We cannot guarantee support, maintenance, or updates to forked and self-hosted instances of this project.
>
> We want to make it as easy as possible for our community to collaborate and push the future of GitBook, which is why we encourage you to contribute to our product directly instead of creating your own version.
This project allows you to self-host the rendering portion of your GitBook published content. Self-hosting has pros and cons.
On the pro side, you can customize the look and feel of your content, and better embed your documentation in your application.
On the con side, you become responsible for the reliability of your published site, and keeping the renderer up-to-date with the changes made to the GitBook platform.
## License
Distributed under the [GNU GPLv3 License](https://github.com/GitBookIO/gitbook/blob/main/LICENSE).
If you plan to distribute the code, you must make the source code public to comply with the GNU GPLv3. To clone in a private repository, acquire a [commercial license](https://www.gitbook.com/pricing).
See `LICENSE` for more information.
## Badges
<p align="left">
<a href="https://gitbook.com"><img src="https://img.shields.io/static/v1?message=Documented%20on%20GitBook&logo=gitbook&logoColor=ffffff&label=%20&labelColor=5c5c5c&color=3F89A1"></a>
<a href="https://gitbook.com"><img src="https://img.shields.io/static/v1?message=Documented%20on%20GitBook&logo=gitbook&logoColor=ffffff&label=%20&labelColor=5c5c5c&color=F4E28D"></a>
<a href="https://gitbook.com"><img src="https://img.shields.io/static/v1?message=Documented%20on%20GitBook&logo=gitbook&logoColor=ffffff&label=%20&labelColor=5c5c5c&color=FDA599"></a>
</p>
```md
[![GitBook](https://img.shields.io/static/v1?message=Documented%20on%20GitBook&logo=gitbook&logoColor=ffffff&label=%20&labelColor=5c5c5c&color=3F89A1)](https://gitbook.com/)
```
-t, --title <name> Name of the book to generate, defaults to repo name
-i, --intro <intro> Description of the book to generate
-g, --github <repo_path> ID of github repo like : username/repo
```
```html
<a href="https://gitbook.com">
<img
src="https://img.shields.io/static/v1?message=Documented%20on%20GitBook&logo=gitbook&logoColor=ffffff&label=%20&labelColor=5c5c5c&color=3F89A1"
/>
</a>
## Book Format
A book is a GitHub repository containing at least 2 files: `README.md` and `SUMMARY.md`.
#### README.md
As usual, it should contains an introduction for your book. It will be automatically added to the final summary.
#### SUMMARY.md
The `SUMMARY.md` defines your book's structure. It should contain a list of chapters, linking to their respective pages.
Example:
```
# Summary
This is the summary of my book.
* [section 1](section1/README.md)
* [example 1](section1/example1.md)
* [example 2](section1/example2.md)
* [section 2](section2/README.md)
* [example 1](section2/example1.md)
```
## Acknowledgements
Files that are not included in the `SUMMARY.md` will not be processed by `gitbook`.
GitBook wouldn't be possible without these projects:
#### Exercises
- [Next.js](https://nextjs.org/)
- [Bun](https://bun.sh/)
- [Tailwind CSS](https://tailwindcss.com/)
- [Framer Motion](https://www.npmjs.com/package/framer-motion)
A book can contain interactive exercises (currently only in Javascript but Python and Ruby are coming soon ;) ). An exercise is a code challenge provided to the reader, which is given a code editor to write a solution which is checked against the book author's validation code.
## Contributors
An exercise is defined by 4 simple parts:
<a href="https://github.com/gitbookIO/gitbook/graphs/contributors">
<img src="https://contrib.rocks/image?repo=gitbookIO/gitbook" />
</a>
* Exercise **Message**/Goals (in markdown/text)
* **Initial** code to show to the user, providing a starting point
* **Solution** code, being a correct solution to the exercise
* **Validation** code that tests the correctness of the user's input
## Legacy GitBook (Deprecated)
Exercises need to start and finish with a separation bar (```---``` or ```***```). It should contain 3 code elements (**base**, **solution** and **validation**).
Our previous version of GitBook and it's CLI tool are now deprecated. You can still view the old repository and it's commits on this [branch](https://github.com/GitbookIO/gitbook/tree/legacy).
---
Define a variable `x` equal to 10.
```js
var x =
```
```js
var x = 10;
```
```js
assert(x == 10);
```
---
+48
View File
@@ -0,0 +1,48 @@
require([
"jQuery",
"utils/storage",
"utils/analytic",
"utils/sharing",
"core/state",
"core/keyboard",
"core/exercise",
"core/progress",
"core/sidebar"
], function($, storage, analytic, sharing, _state, keyboard, exercise, progress, sidebar){
$(document).ready(function() {
var state = _state();
var $book = state.$book;
// Initialize storage
storage.setBaseKey(state.githubId);
// Tract page view
analytic.track("View");
// Init sidebar
sidebar.init();
// Init keyboard
keyboard.init();
// Star and watch count
$.getJSON("https://api.github.com/repos/"+state.githubId)
.done(function(repo) {
$book.find(".count-star span").text(repo.stargazers_count);
$book.find(".count-watch span").text(repo.subscribers_count);
});
// Bind exercise
exercise.init();
// Bind sharing button
sharing.init();
// Show progress
progress.show();
// Focus on content
$(".book-body").focus();
});
});
+50
View File
@@ -0,0 +1,50 @@
define([
"jQuery",
"utils/execute",
"utils/analytic",
"core/state"
], function($, execute, analytic, state){
// Bind an exercise
var prepareExercise = function($exercise) {
var codeSolution = $exercise.find(".code-solution").text();
var codeValidation = $exercise.find(".code-validation").text();
var editor = ace.edit($exercise.find(".editor").get(0));
editor.setTheme("ace/theme/tomorrow");
editor.getSession().setUseWorker(false);
editor.getSession().setMode("ace/mode/javascript");
// Submit: test code
$exercise.find(".action-submit").click(function(e) {
e.preventDefault();
analytic.track("exercise.submit");
execute(editor.getValue(), codeValidation, function(err, result) {
$exercise.toggleClass("return-error", err != null);
$exercise.toggleClass("return-success", err == null);
if (err) $exercise.find(".alert-danger").text(err.message || err);
});
});
// Set solution
$exercise.find(".action-solution").click(function(e) {
e.preventDefault();
editor.setValue(codeSolution);
editor.gotoLine(0);
});
};
// Prepare all exercise
var init = function() {
state().$book.find("section.exercise").each(function() {
prepareExercise($(this));
});
};
return {
init: init,
prepare: prepareExercise
};
});
+31
View File
@@ -0,0 +1,31 @@
define([
"jQuery",
"Mousetrap",
"core/navigation",
"core/sidebar"
], function($, Mousetrap, navigation, sidebar){
// Bind keyboard shortcuts
var init = function() {
// Next
Mousetrap.bind(['right'], function(e) {
navigation.goNext();
return false;
});
// Prev
Mousetrap.bind(['left'], function(e) {
navigation.goPrev();
return false;
});
// Toggle Summary
Mousetrap.bind(['s'], function(e) {
sidebar.toggle();
return false;
});
};
return {
init: init
};
});
+17
View File
@@ -0,0 +1,17 @@
define([
"jQuery"
], function($) {
var goNext = function() {
var url = $("link[rel='next']").attr("href");
if (url) location.href = url;
};
var goPrev = function() {
var url = $("link[rel='prev']").attr("href");
if (url) location.href = url;
};
return {
goNext: goNext,
goPrev: goPrev
};
});
+66
View File
@@ -0,0 +1,66 @@
define([
"lodash",
"jQuery",
"utils/storage",
"core/state"
], function(_, $, storage, state) {
// Get current level
var getCurrentLevel = function() {
return state().level;
};
// Return all levels
var getLevels = function() {
var levels = $(".book-summary li[data-level]");
return _.map(levels, function(level) {
return $(level).data("level").toString();
});
};
// Return a map chapter -> number (timestamp)
var getProgress = function() {
// Current level
var progress = storage.get("progress", {});
// Levels
var levels = getLevels();
_.each(levels, function(level) {
progress[level] = progress[level] || 0;
});
return progress;
};
// Change value of progress for a level
var markProgress = function(level, state) {
if (state == null) state = true;
var progress = getProgress();
progress[level] = state? Date.now() : 0;
storage.set("progress", progress);
};
// Show progress
var showProgress = function() {
// Update progress
var progress = getProgress();
var $summary = $(".book-summary");
_.each(progress, function(value, level) {
$summary.find("li[data-level='"+level+"']").toggleClass("done", value > 0);
});
// Mark current progress
markProgress(getCurrentLevel(), true);
};
return {
'current': getCurrentLevel,
'levels': getLevels,
'get': getProgress,
'mark': markProgress,
'show': showProgress
};
});
+42
View File
@@ -0,0 +1,42 @@
define([
"utils/storage",
"utils/platform",
"core/state"
], function(storage, platform, state) {
// Toggle sidebar with or withour animation
var toggleSidebar = function(_state, animation) {
if (-state != null && isOpen() == _state) return;
if (animation == null) animation = true;
var $book = state().$book;
$book.toggleClass("without-animation", !animation);
$book.toggleClass("with-summary", _state);
storage.set("sidebar", isOpen());
};
// Return true if sidebar is open
var isOpen = function() {
return state().$book.hasClass("with-summary");
};
// Prepare sidebar: state and toggle button
var init = function() {
var $book = state().$book;
// Toggle summary
$book.find(".book-header .toggle-summary").click(function(e) {
e.preventDefault();
toggleSidebar();
});
// Init last state if not mobile and not homepage
toggleSidebar(platform.isMobile ? false : storage.get("sidebar", true), false);
};
return {
init: init,
toggle: toggleSidebar
}
});
+14
View File
@@ -0,0 +1,14 @@
define([
"jQuery"
], function() {
return function() {
var $book = $(".book");
return {
'$book': $book,
'githubId': $book.data("github"),
'level': $book.data("level")
};
};
});
+18
View File
@@ -0,0 +1,18 @@
define([], function() {
var isAvailable = function() {
return (typeof mixpanel !== "undefined");
};
var track = function(event, data) {
if (!isAvailable()) {
console.log("tracking not available!");
return;
}
mixpanel.track(event, data);
};
return {
isAvailable: isAvailable,
track: track
};
});
+82
View File
@@ -0,0 +1,82 @@
define(function(){
var evalJS = function(code, callback) {
var ready = false;
var finished = false;
var finish = function() {
if(finished) {
return console.error('Already finished');
}
finished = true;
return callback.apply(null, arguments);
};
var jsrepl;
// Handles all our events
var eventHandler = function(data, eventType) {
console.log([eventType, data]);
switch(eventType) {
case 'progress':
// Update UI loading bar
break;
case 'timeout':
finish(new Error(data));
break;
case 'result':
finish(null, {
value: data,
type: 'result'
});
break;
case 'error':
if(ready) {
return finish(null, {
value: data,
type: 'error'
});
}
return finish(new Error(data));
break
case 'ready':
// We're good to get results and stuff back now
ready = true;
// Eval our code now that the runtime is ready
jsrepl.eval(code);
break;
default:
console.log('Unhandled event =', eventType, 'data =', data);
}
};
jsrepl = new JSREPL({
input: eventHandler,
output: eventHandler,
result: eventHandler,
error: eventHandler,
progress: eventHandler,
timeout: {
time: 30000,
callback: eventHandler
}
});
jsrepl.loadLanguage('javascript', eventHandler);
};
var ass = "function assert(condition, message) { \nif (!condition) { \n throw message || \"Assertion failed\"; \n } \n }\n";
var execute = function(solution, validation, callback) {
// Validate with validation code
var code = [solution, ass, validation].join(";\n");
evalJS(code, function(err, res) {
if(err) return callback(err);
if (res.type == "error") callback(new Error(res.value));
else callback(null, res.value);
});
};
return execute;
});
+5
View File
@@ -0,0 +1,5 @@
define([], function() {
return {
isMobile: /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)
};
});
+33
View File
@@ -0,0 +1,33 @@
define([
"jQuery"
], function($) {
var url = location.href;
var title = $("title").text();
var types = {
"twitter": function($el) {
window.open("http://twitter.com/home?status="+encodeURIComponent(title+" "+url))
},
"facebook": function($el) {
window.open("http://www.facebook.com/sharer/sharer.php?s=100&p[url]="+encodeURIComponent(url))
},
"google-plus": function($el) {
window.open("https://plus.google.com/share?url="+encodeURIComponent(url))
}
};
// Bind all sharing button
var init = function() {
$("a[data-sharing]").click(function(e) {
if (e) e.preventDefault();
var type = $(this).data("sharing");
types[type]($(this));
})
};
return {
init: init
};
});
+28
View File
@@ -0,0 +1,28 @@
define(function(){
var baseKey = "";
/*
* Simple module for storing data in the browser's local storage
*/
return {
setBaseKey: function(key) {
baseKey = key;
},
set: function(key, value) {
key = baseKey+":"+key;
localStorage[key] = JSON.stringify(value);
},
get: function(key, def) {
key = baseKey+":"+key;
try {
return JSON.parse(localStorage[key]) || def;
} catch(err) {
return localStorage[key] || def;
}
},
remove: function(key) {
key = baseKey+":"+key;
localStorage.removeItem(key);
}
};
});
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
+953
View File
@@ -0,0 +1,953 @@
/*global define:false */
/**
* Copyright 2013 Craig Campbell
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*
* Mousetrap is a simple keyboard shortcut library for Javascript with
* no external dependencies
*
* @version 1.4.6
* @url craig.is/killing/mice
*/
(function(window, document, undefined) {
/**
* mapping of special keycodes to their corresponding keys
*
* everything in this dictionary cannot use keypress events
* so it has to be here to map to the correct keycodes for
* keyup/keydown events
*
* @type {Object}
*/
var _MAP = {
8: 'backspace',
9: 'tab',
13: 'enter',
16: 'shift',
17: 'ctrl',
18: 'alt',
20: 'capslock',
27: 'esc',
32: 'space',
33: 'pageup',
34: 'pagedown',
35: 'end',
36: 'home',
37: 'left',
38: 'up',
39: 'right',
40: 'down',
45: 'ins',
46: 'del',
91: 'meta',
93: 'meta',
224: 'meta'
},
/**
* mapping for special characters so they can support
*
* this dictionary is only used incase you want to bind a
* keyup or keydown event to one of these keys
*
* @type {Object}
*/
_KEYCODE_MAP = {
106: '*',
107: '+',
109: '-',
110: '.',
111 : '/',
186: ';',
187: '=',
188: ',',
189: '-',
190: '.',
191: '/',
192: '`',
219: '[',
220: '\\',
221: ']',
222: '\''
},
/**
* this is a mapping of keys that require shift on a US keypad
* back to the non shift equivelents
*
* this is so you can use keyup events with these keys
*
* note that this will only work reliably on US keyboards
*
* @type {Object}
*/
_SHIFT_MAP = {
'~': '`',
'!': '1',
'@': '2',
'#': '3',
'$': '4',
'%': '5',
'^': '6',
'&': '7',
'*': '8',
'(': '9',
')': '0',
'_': '-',
'+': '=',
':': ';',
'\"': '\'',
'<': ',',
'>': '.',
'?': '/',
'|': '\\'
},
/**
* this is a list of special strings you can use to map
* to modifier keys when you specify your keyboard shortcuts
*
* @type {Object}
*/
_SPECIAL_ALIASES = {
'option': 'alt',
'command': 'meta',
'return': 'enter',
'escape': 'esc',
'mod': /Mac|iPod|iPhone|iPad/.test(navigator.platform) ? 'meta' : 'ctrl'
},
/**
* variable to store the flipped version of _MAP from above
* needed to check if we should use keypress or not when no action
* is specified
*
* @type {Object|undefined}
*/
_REVERSE_MAP,
/**
* a list of all the callbacks setup via Mousetrap.bind()
*
* @type {Object}
*/
_callbacks = {},
/**
* direct map of string combinations to callbacks used for trigger()
*
* @type {Object}
*/
_directMap = {},
/**
* keeps track of what level each sequence is at since multiple
* sequences can start out with the same sequence
*
* @type {Object}
*/
_sequenceLevels = {},
/**
* variable to store the setTimeout call
*
* @type {null|number}
*/
_resetTimer,
/**
* temporary state where we will ignore the next keyup
*
* @type {boolean|string}
*/
_ignoreNextKeyup = false,
/**
* temporary state where we will ignore the next keypress
*
* @type {boolean}
*/
_ignoreNextKeypress = false,
/**
* are we currently inside of a sequence?
* type of action ("keyup" or "keydown" or "keypress") or false
*
* @type {boolean|string}
*/
_nextExpectedAction = false;
/**
* loop through the f keys, f1 to f19 and add them to the map
* programatically
*/
for (var i = 1; i < 20; ++i) {
_MAP[111 + i] = 'f' + i;
}
/**
* loop through to map numbers on the numeric keypad
*/
for (i = 0; i <= 9; ++i) {
_MAP[i + 96] = i;
}
/**
* cross browser add event method
*
* @param {Element|HTMLDocument} object
* @param {string} type
* @param {Function} callback
* @returns void
*/
function _addEvent(object, type, callback) {
if (object.addEventListener) {
object.addEventListener(type, callback, false);
return;
}
object.attachEvent('on' + type, callback);
}
/**
* takes the event and returns the key character
*
* @param {Event} e
* @return {string}
*/
function _characterFromEvent(e) {
// for keypress events we should return the character as is
if (e.type == 'keypress') {
var character = String.fromCharCode(e.which);
// if the shift key is not pressed then it is safe to assume
// that we want the character to be lowercase. this means if
// you accidentally have caps lock on then your key bindings
// will continue to work
//
// the only side effect that might not be desired is if you
// bind something like 'A' cause you want to trigger an
// event when capital A is pressed caps lock will no longer
// trigger the event. shift+a will though.
if (!e.shiftKey) {
character = character.toLowerCase();
}
return character;
}
// for non keypress events the special maps are needed
if (_MAP[e.which]) {
return _MAP[e.which];
}
if (_KEYCODE_MAP[e.which]) {
return _KEYCODE_MAP[e.which];
}
// if it is not in the special map
// with keydown and keyup events the character seems to always
// come in as an uppercase character whether you are pressing shift
// or not. we should make sure it is always lowercase for comparisons
return String.fromCharCode(e.which).toLowerCase();
}
/**
* checks if two arrays are equal
*
* @param {Array} modifiers1
* @param {Array} modifiers2
* @returns {boolean}
*/
function _modifiersMatch(modifiers1, modifiers2) {
return modifiers1.sort().join(',') === modifiers2.sort().join(',');
}
/**
* resets all sequence counters except for the ones passed in
*
* @param {Object} doNotReset
* @returns void
*/
function _resetSequences(doNotReset) {
doNotReset = doNotReset || {};
var activeSequences = false,
key;
for (key in _sequenceLevels) {
if (doNotReset[key]) {
activeSequences = true;
continue;
}
_sequenceLevels[key] = 0;
}
if (!activeSequences) {
_nextExpectedAction = false;
}
}
/**
* finds all callbacks that match based on the keycode, modifiers,
* and action
*
* @param {string} character
* @param {Array} modifiers
* @param {Event|Object} e
* @param {string=} sequenceName - name of the sequence we are looking for
* @param {string=} combination
* @param {number=} level
* @returns {Array}
*/
function _getMatches(character, modifiers, e, sequenceName, combination, level) {
var i,
callback,
matches = [],
action = e.type;
// if there are no events related to this keycode
if (!_callbacks[character]) {
return [];
}
// if a modifier key is coming up on its own we should allow it
if (action == 'keyup' && _isModifier(character)) {
modifiers = [character];
}
// loop through all callbacks for the key that was pressed
// and see if any of them match
for (i = 0; i < _callbacks[character].length; ++i) {
callback = _callbacks[character][i];
// if a sequence name is not specified, but this is a sequence at
// the wrong level then move onto the next match
if (!sequenceName && callback.seq && _sequenceLevels[callback.seq] != callback.level) {
continue;
}
// if the action we are looking for doesn't match the action we got
// then we should keep going
if (action != callback.action) {
continue;
}
// if this is a keypress event and the meta key and control key
// are not pressed that means that we need to only look at the
// character, otherwise check the modifiers as well
//
// chrome will not fire a keypress if meta or control is down
// safari will fire a keypress if meta or meta+shift is down
// firefox will fire a keypress if meta or control is down
if ((action == 'keypress' && !e.metaKey && !e.ctrlKey) || _modifiersMatch(modifiers, callback.modifiers)) {
// when you bind a combination or sequence a second time it
// should overwrite the first one. if a sequenceName or
// combination is specified in this call it does just that
//
// @todo make deleting its own method?
var deleteCombo = !sequenceName && callback.combo == combination;
var deleteSequence = sequenceName && callback.seq == sequenceName && callback.level == level;
if (deleteCombo || deleteSequence) {
_callbacks[character].splice(i, 1);
}
matches.push(callback);
}
}
return matches;
}
/**
* takes a key event and figures out what the modifiers are
*
* @param {Event} e
* @returns {Array}
*/
function _eventModifiers(e) {
var modifiers = [];
if (e.shiftKey) {
modifiers.push('shift');
}
if (e.altKey) {
modifiers.push('alt');
}
if (e.ctrlKey) {
modifiers.push('ctrl');
}
if (e.metaKey) {
modifiers.push('meta');
}
return modifiers;
}
/**
* prevents default for this event
*
* @param {Event} e
* @returns void
*/
function _preventDefault(e) {
if (e.preventDefault) {
e.preventDefault();
return;
}
e.returnValue = false;
}
/**
* stops propogation for this event
*
* @param {Event} e
* @returns void
*/
function _stopPropagation(e) {
if (e.stopPropagation) {
e.stopPropagation();
return;
}
e.cancelBubble = true;
}
/**
* actually calls the callback function
*
* if your callback function returns false this will use the jquery
* convention - prevent default and stop propogation on the event
*
* @param {Function} callback
* @param {Event} e
* @returns void
*/
function _fireCallback(callback, e, combo, sequence) {
// if this event should not happen stop here
if (Mousetrap.stopCallback(e, e.target || e.srcElement, combo, sequence)) {
return;
}
if (callback(e, combo) === false) {
_preventDefault(e);
_stopPropagation(e);
}
}
/**
* handles a character key event
*
* @param {string} character
* @param {Array} modifiers
* @param {Event} e
* @returns void
*/
function _handleKey(character, modifiers, e) {
var callbacks = _getMatches(character, modifiers, e),
i,
doNotReset = {},
maxLevel = 0,
processedSequenceCallback = false;
// Calculate the maxLevel for sequences so we can only execute the longest callback sequence
for (i = 0; i < callbacks.length; ++i) {
if (callbacks[i].seq) {
maxLevel = Math.max(maxLevel, callbacks[i].level);
}
}
// loop through matching callbacks for this key event
for (i = 0; i < callbacks.length; ++i) {
// fire for all sequence callbacks
// this is because if for example you have multiple sequences
// bound such as "g i" and "g t" they both need to fire the
// callback for matching g cause otherwise you can only ever
// match the first one
if (callbacks[i].seq) {
// only fire callbacks for the maxLevel to prevent
// subsequences from also firing
//
// for example 'a option b' should not cause 'option b' to fire
// even though 'option b' is part of the other sequence
//
// any sequences that do not match here will be discarded
// below by the _resetSequences call
if (callbacks[i].level != maxLevel) {
continue;
}
processedSequenceCallback = true;
// keep a list of which sequences were matches for later
doNotReset[callbacks[i].seq] = 1;
_fireCallback(callbacks[i].callback, e, callbacks[i].combo, callbacks[i].seq);
continue;
}
// if there were no sequence matches but we are still here
// that means this is a regular match so we should fire that
if (!processedSequenceCallback) {
_fireCallback(callbacks[i].callback, e, callbacks[i].combo);
}
}
// if the key you pressed matches the type of sequence without
// being a modifier (ie "keyup" or "keypress") then we should
// reset all sequences that were not matched by this event
//
// this is so, for example, if you have the sequence "h a t" and you
// type "h e a r t" it does not match. in this case the "e" will
// cause the sequence to reset
//
// modifier keys are ignored because you can have a sequence
// that contains modifiers such as "enter ctrl+space" and in most
// cases the modifier key will be pressed before the next key
//
// also if you have a sequence such as "ctrl+b a" then pressing the
// "b" key will trigger a "keypress" and a "keydown"
//
// the "keydown" is expected when there is a modifier, but the
// "keypress" ends up matching the _nextExpectedAction since it occurs
// after and that causes the sequence to reset
//
// we ignore keypresses in a sequence that directly follow a keydown
// for the same character
var ignoreThisKeypress = e.type == 'keypress' && _ignoreNextKeypress;
if (e.type == _nextExpectedAction && !_isModifier(character) && !ignoreThisKeypress) {
_resetSequences(doNotReset);
}
_ignoreNextKeypress = processedSequenceCallback && e.type == 'keydown';
}
/**
* handles a keydown event
*
* @param {Event} e
* @returns void
*/
function _handleKeyEvent(e) {
// normalize e.which for key events
// @see http://stackoverflow.com/questions/4285627/javascript-keycode-vs-charcode-utter-confusion
if (typeof e.which !== 'number') {
e.which = e.keyCode;
}
var character = _characterFromEvent(e);
// no character found then stop
if (!character) {
return;
}
// need to use === for the character check because the character can be 0
if (e.type == 'keyup' && _ignoreNextKeyup === character) {
_ignoreNextKeyup = false;
return;
}
Mousetrap.handleKey(character, _eventModifiers(e), e);
}
/**
* determines if the keycode specified is a modifier key or not
*
* @param {string} key
* @returns {boolean}
*/
function _isModifier(key) {
return key == 'shift' || key == 'ctrl' || key == 'alt' || key == 'meta';
}
/**
* called to set a 1 second timeout on the specified sequence
*
* this is so after each key press in the sequence you have 1 second
* to press the next key before you have to start over
*
* @returns void
*/
function _resetSequenceTimer() {
clearTimeout(_resetTimer);
_resetTimer = setTimeout(_resetSequences, 1000);
}
/**
* reverses the map lookup so that we can look for specific keys
* to see what can and can't use keypress
*
* @return {Object}
*/
function _getReverseMap() {
if (!_REVERSE_MAP) {
_REVERSE_MAP = {};
for (var key in _MAP) {
// pull out the numeric keypad from here cause keypress should
// be able to detect the keys from the character
if (key > 95 && key < 112) {
continue;
}
if (_MAP.hasOwnProperty(key)) {
_REVERSE_MAP[_MAP[key]] = key;
}
}
}
return _REVERSE_MAP;
}
/**
* picks the best action based on the key combination
*
* @param {string} key - character for key
* @param {Array} modifiers
* @param {string=} action passed in
*/
function _pickBestAction(key, modifiers, action) {
// if no action was picked in we should try to pick the one
// that we think would work best for this key
if (!action) {
action = _getReverseMap()[key] ? 'keydown' : 'keypress';
}
// modifier keys don't work as expected with keypress,
// switch to keydown
if (action == 'keypress' && modifiers.length) {
action = 'keydown';
}
return action;
}
/**
* binds a key sequence to an event
*
* @param {string} combo - combo specified in bind call
* @param {Array} keys
* @param {Function} callback
* @param {string=} action
* @returns void
*/
function _bindSequence(combo, keys, callback, action) {
// start off by adding a sequence level record for this combination
// and setting the level to 0
_sequenceLevels[combo] = 0;
/**
* callback to increase the sequence level for this sequence and reset
* all other sequences that were active
*
* @param {string} nextAction
* @returns {Function}
*/
function _increaseSequence(nextAction) {
return function() {
_nextExpectedAction = nextAction;
++_sequenceLevels[combo];
_resetSequenceTimer();
};
}
/**
* wraps the specified callback inside of another function in order
* to reset all sequence counters as soon as this sequence is done
*
* @param {Event} e
* @returns void
*/
function _callbackAndReset(e) {
_fireCallback(callback, e, combo);
// we should ignore the next key up if the action is key down
// or keypress. this is so if you finish a sequence and
// release the key the final key will not trigger a keyup
if (action !== 'keyup') {
_ignoreNextKeyup = _characterFromEvent(e);
}
// weird race condition if a sequence ends with the key
// another sequence begins with
setTimeout(_resetSequences, 10);
}
// loop through keys one at a time and bind the appropriate callback
// function. for any key leading up to the final one it should
// increase the sequence. after the final, it should reset all sequences
//
// if an action is specified in the original bind call then that will
// be used throughout. otherwise we will pass the action that the
// next key in the sequence should match. this allows a sequence
// to mix and match keypress and keydown events depending on which
// ones are better suited to the key provided
for (var i = 0; i < keys.length; ++i) {
var isFinal = i + 1 === keys.length;
var wrappedCallback = isFinal ? _callbackAndReset : _increaseSequence(action || _getKeyInfo(keys[i + 1]).action);
_bindSingle(keys[i], wrappedCallback, action, combo, i);
}
}
/**
* Converts from a string key combination to an array
*
* @param {string} combination like "command+shift+l"
* @return {Array}
*/
function _keysFromString(combination) {
if (combination === '+') {
return ['+'];
}
return combination.split('+');
}
/**
* Gets info for a specific key combination
*
* @param {string} combination key combination ("command+s" or "a" or "*")
* @param {string=} action
* @returns {Object}
*/
function _getKeyInfo(combination, action) {
var keys,
key,
i,
modifiers = [];
// take the keys from this pattern and figure out what the actual
// pattern is all about
keys = _keysFromString(combination);
for (i = 0; i < keys.length; ++i) {
key = keys[i];
// normalize key names
if (_SPECIAL_ALIASES[key]) {
key = _SPECIAL_ALIASES[key];
}
// if this is not a keypress event then we should
// be smart about using shift keys
// this will only work for US keyboards however
if (action && action != 'keypress' && _SHIFT_MAP[key]) {
key = _SHIFT_MAP[key];
modifiers.push('shift');
}
// if this key is a modifier then add it to the list of modifiers
if (_isModifier(key)) {
modifiers.push(key);
}
}
// depending on what the key combination is
// we will try to pick the best event for it
action = _pickBestAction(key, modifiers, action);
return {
key: key,
modifiers: modifiers,
action: action
};
}
/**
* binds a single keyboard combination
*
* @param {string} combination
* @param {Function} callback
* @param {string=} action
* @param {string=} sequenceName - name of sequence if part of sequence
* @param {number=} level - what part of the sequence the command is
* @returns void
*/
function _bindSingle(combination, callback, action, sequenceName, level) {
// store a direct mapped reference for use with Mousetrap.trigger
_directMap[combination + ':' + action] = callback;
// make sure multiple spaces in a row become a single space
combination = combination.replace(/\s+/g, ' ');
var sequence = combination.split(' '),
info;
// if this pattern is a sequence of keys then run through this method
// to reprocess each pattern one key at a time
if (sequence.length > 1) {
_bindSequence(combination, sequence, callback, action);
return;
}
info = _getKeyInfo(combination, action);
// make sure to initialize array if this is the first time
// a callback is added for this key
_callbacks[info.key] = _callbacks[info.key] || [];
// remove an existing match if there is one
_getMatches(info.key, info.modifiers, {type: info.action}, sequenceName, combination, level);
// add this call back to the array
// if it is a sequence put it at the beginning
// if not put it at the end
//
// this is important because the way these are processed expects
// the sequence ones to come first
_callbacks[info.key][sequenceName ? 'unshift' : 'push']({
callback: callback,
modifiers: info.modifiers,
action: info.action,
seq: sequenceName,
level: level,
combo: combination
});
}
/**
* binds multiple combinations to the same callback
*
* @param {Array} combinations
* @param {Function} callback
* @param {string|undefined} action
* @returns void
*/
function _bindMultiple(combinations, callback, action) {
for (var i = 0; i < combinations.length; ++i) {
_bindSingle(combinations[i], callback, action);
}
}
// start!
_addEvent(document, 'keypress', _handleKeyEvent);
_addEvent(document, 'keydown', _handleKeyEvent);
_addEvent(document, 'keyup', _handleKeyEvent);
var Mousetrap = {
/**
* binds an event to mousetrap
*
* can be a single key, a combination of keys separated with +,
* an array of keys, or a sequence of keys separated by spaces
*
* be sure to list the modifier keys first to make sure that the
* correct key ends up getting bound (the last key in the pattern)
*
* @param {string|Array} keys
* @param {Function} callback
* @param {string=} action - 'keypress', 'keydown', or 'keyup'
* @returns void
*/
bind: function(keys, callback, action) {
keys = keys instanceof Array ? keys : [keys];
_bindMultiple(keys, callback, action);
return this;
},
/**
* unbinds an event to mousetrap
*
* the unbinding sets the callback function of the specified key combo
* to an empty function and deletes the corresponding key in the
* _directMap dict.
*
* TODO: actually remove this from the _callbacks dictionary instead
* of binding an empty function
*
* the keycombo+action has to be exactly the same as
* it was defined in the bind method
*
* @param {string|Array} keys
* @param {string} action
* @returns void
*/
unbind: function(keys, action) {
return Mousetrap.bind(keys, function() {}, action);
},
/**
* triggers an event that has already been bound
*
* @param {string} keys
* @param {string=} action
* @returns void
*/
trigger: function(keys, action) {
if (_directMap[keys + ':' + action]) {
_directMap[keys + ':' + action]({}, keys);
}
return this;
},
/**
* resets the library back to its initial state. this is useful
* if you want to clear out the current keyboard shortcuts and bind
* new ones - for example if you switch to another page
*
* @returns void
*/
reset: function() {
_callbacks = {};
_directMap = {};
return this;
},
/**
* should we stop this event before firing off callbacks
*
* @param {Event} e
* @param {Element} element
* @return {boolean}
*/
stopCallback: function(e, element) {
// if the element has the class "mousetrap" then no need to stop
if ((' ' + element.className + ' ').indexOf(' mousetrap ') > -1) {
return false;
}
// stop for input, select, and textarea
return element.tagName == 'INPUT' || element.tagName == 'SELECT' || element.tagName == 'TEXTAREA' || element.isContentEditable;
},
/**
* exposes _handleKey publicly so it can be overwritten by extensions
*/
handleKey: _handleKey
};
// expose mousetrap to the global object
window.Mousetrap = Mousetrap;
// expose mousetrap as an AMD module
if (typeof define === 'function' && define.amd) {
define(Mousetrap);
}
}) (window, document);
File diff suppressed because it is too large Load Diff

Some files were not shown because too many files have changed in this diff Show More