misc/ebrowser/README.md

   1 ### [Ebrowser](https://github.com/torappinfo/ebrowser): keyboard-friendly minimal suckless web browser
   2 Ebrowser is designed with the philosophy of [Android uweb browser](https://github.com/torappinfo/uweb) ([gitlab](https://gitlab.com/jamesfengcao/uweb)).
   3
   4 - lightweight (less than 20k bytes) without bundled electron.
   5 - much less memory footprint than edge/chrome browser and highly performant.
   6 - keyboard friendly with vim-style keymaps and command line support in address bar.
   7 - <a href="https://uweb.surge.sh/en/redirect/index.html#" onclick="if(notRepo()){location='../redirect/index.html#';return false;}">global redirection</a> to bypass censorship.
   8 - user CSS/JS at will. Ex. pressing "md" in no-focus mode to preview markdown file.
   9 - global CSS/JS for all sites at will.
  10 - CSS/JS for domains, similar to [uweb](https://jamesfengcao.gitlab.io/uweb/en/sitejs/index.html), but use sitejs/[domain].js or sitecss/[domain].css, not [domain root].js/css.
  11 - customizable.
  12
  13 Note: Usually electron apps are heavyweight as they use browsers for simple things. Ebrowser uses core chromium effectively and very lightweight. Recommend to install electron separately.
  14
  15 #### Installing (for Windows, MacOS and Linux)
  16 ##### Install with prebuilt binaries
  17 You can find prebuilt binaries [here](https://github.com/torappinfo/ebrowser/releases).
  18
  19 ##### Install ebrowser and electron separatedly
  20 ###### Install ebrowser
  21 Either download and unzip ebrowser package directly from any of npm mirror sites like [npmmirror](https://npmmirror.com/package/ebrowser) or with nodejs by
  22
  23     npm install ebrowser
  24
  25 OR
  26
  27     git clone https://github.com/torappinfo/ebrowser
  28
  29 OR "git clone"/download files directly from any of [mirror repositories](https://gitlab.com/jamesfengcao/uweb/-/blob/master/en/mirrors.md) and ebrowser is under the folder "misc/ebrowser".
  30
  31 ###### Install electron
  32 Before you can run ebrowser, you need to install electron either with nodejs by
  33
  34     npm install electron
  35
  36 OR download and unzip electron binary directly from [github](https://github.com/electron/electron/releases) or mirrors like [npmmirror](https://registry.npmmirror.com/binary.html?path=electron).
  37
  38 ###### Run ebrowser
  39
  40     electron ~/node_modules/ebrowser
  41
  42 OR
  43
  44     electron [the-path-of-folder-with-downloaded-ebrowser-files]
  45
  46 ##### Update app quickly without updating chromium
  47 Pressing "Alt" to show the menu bar and choose "Check for updates" under "Help". OR
  48
  49 Type ":update" in the address bar and press "enter" key to update.
  50
  51 Mirror urls could be used like ":update https://uwebzh.netlify.app/misc/ebrowser". All the mirrors listed on [uweb browser](https://uwebzh.netlify.app/en/readme/index.html) could be used. The update url needs to be changed accordingly to be the folder "misc/ebrowser" under the mirror site root url.
  52
  53 #### Key shortcuts
  54 - Alt: show menu
  55 - ALT+<-: go backward
  56 - ALT+->: go forward
  57 - CTRL+C: stop loading
  58 - CTRL+G: address bar to show page url
  59 - CTRL+L: focus to address bar
  60 - CTRL+T: new Tab
  61 - CTRL+SHIFT+T: restore closed Tab
  62 - CTRL+TAB: switch to next tab
  63 - CTRL+SHIFT+TAB: switch to previous tab
  64 - CTRL+W: close Tab
  65 - CTRL+SHIFT+R: enable global redirection ("gredirect.json")
  66 - CTRL+R: disable global redirection
  67 - ESC: remove focus. similar to vi normal mode.
  68 - F1: Help
  69 - F5: page refresh/reload
  70 - F12: devtools
  71
  72 #### Address bar commands
  73 Like any popular browser, the very first word in address bar if defined in "search.json" identifies a search engine. Moreover, the address bar serves as command line interface:
  74 - "/" for find-in-page
  75 - ":" for address bar commands
  76   - ac [bookmark/history path w/o ext] : load ".rec" file for autocomplete.
  77   - b [bookmarkfilename w/o ext] : bookmark current page in file.
  78   - bjs : Browser-level JavaScript execution.
  79   - bml [filename w/o extension]: load/execute the javascript file.
  80   - cert : allow invalid certificates w/o arguments, otherwise restore to default.
  81   - clear : the arguments could be
  82     - cache : clear cache
  83     - dns : clear dns cache
  84     - storage: clear site storage data.
  85     - {[options](https://www.electronjs.org/docs/latest/api/session#sescleardataoptions)}
  86   - ext [extension path]: load unpacked Chrome extension.
  87   - gr [gredirect index]: global redirection with corresponding index. Use the first global redirection url if no argument. Disable global redirection with any index out of the range.
  88   - js [js code] : execute JS code at OS level. Note: "javascript:..." is special url and thus works in the current web page, while ":js ..." commands can do any OS operations.
  89   - nc/uc : No Cookie forwarding/Use Cookie forwarding with global redirection.
  90   - nr/ur for No/Use "redirect.json" for domain redirection.
  91   - np : no proxy.
  92   - up [proxyName] : use proxy. privous proxy or the first proxy in proxy.json w/o [proxyName]. ":up" command also disables global and domain redirections, which are not restored by ":np".
  93   - ua [useragentName] : set user agent for future tabs. default user agent w/o arguments.
  94   - update [filename] : update the app w/o argument, otherwise retrive the [filename] from remote. The filename could be any file on [mirror sites](https://jamesfengcao.gitlab.io/uweb/en/readme/index.html) (this repository is part of it).
  95   - pdf [filename w/o extension] {[options](https://www.electronjs.org/docs/latest/api/web-contents#contentsprinttopdfoptions)} : print to PDF file. All arguments are optional; empty option "{}" to capture long screenshot as vector graphics.
  96 - "!" address bar commands
  97   "!xx ..." evaluates "xx.js" with the whole text as arguments[0].
  98 - i: internal urls, which will be consistent with [uweb](https://jamesfengcao.gitlab.io/uweb/en/links/index.html).
  99   - "i:0/js/xxx.js:[url]" loads the "[url]" with bookmarklet "js/xxx.js".
 100
 101 #### Commands in no-focus mode (this mode is similar to vi Normal mode)
 102 Pressing "ESC" to enter no-focus mode if not sure.
 103 - ":" for address bar commands
 104 - "/" for find-in-page with address bar
 105 - "!" for "!" address bar commands
 106
 107 The other commands are defined in "mapkeys.json", which will map keys to address bar commands.
 108
 109 #### Configuration files
 110 - "config": lines of address bar commands.
 111 - "search.json": <a href="https://jamesfengcao.gitlab.io/uweb/en/search/index.html" onclick="if(notRepo()){location='../search/index.html#';return false;}">search engines</a> as shortcut-queryUrl pairs, where "%s" would be replaced by search query.
 112 - "default.autoc": predefined strings for address bar auto completion.
 113 - "gredirect.json": global redirection urls as array of urls
 114 - "redirect.json": domain-replacementDomain pairs, default to be applied.
 115 - "mapkeys.json": keys-addressbarCommands pairs. The addressbar commands are multiple lines of address bar command separated by "\n".
 116 - "proxy.json": name-[ProxyConfig](https://www.electronjs.org/docs/latest/api/structures/proxy-config) pairs
 117 - "uas.json" : name-<a href="https://jamesfengcao.gitlab.io/uweb/en/useragents/index.html" onclick="if(notRepo()){location='../useragents/index.html#';return false;}">useragent</a> pairs.
 118 - Customized menus: json files as array of strings with menuitem name and address bar commands alternately.
 119   - "menu.json": array of strings for <a href="https://jamesfengcao.gitlab.io/uweb/en/urls/index.html" onclick="if(notRepo()){location='../urls/index.html#';return false;}">user-defined menus</a>. The array has submenu name and address bar commands alternately. The odd-indexed strings are address bar commands with "%u" as the downloaded url.
 120   - "select.json": to define menus for text selections. The odd-indexed strings are address bar commands with "%s" as the text selection.
 121   - "download.json" : array of strings to define context menu and buttons for downloading dialog. The even-indexed strings are texts to show on the button. The odd-indexed strings are address bar commands with "%u" as the downloaded url.
 122
 123 #### Javascript at three levels
 124 - Web page: url like "javascript:" or bookmarklet command ":bml" runs in web page.
 125 - Browser (or renderer process) :
 126   - ":bjs" to execute the following js code at browser level.
 127   - "!xx" evaluates "xx.js", which could manipulate address bar etc.
 128 - OS level (or main process) : ":js" to execute the following js code with all OS APIs available.
 129
 130 ##### examples for ":js"/":bjs" commands
 131
 132     :js bJS=true //allow external Javascript files for web pages
 133     :js bJS=false //disallow external Javascript files for web pages
 134     :bjs bHistory=true //to record url history
 135     :bjs bQueryHistory=true //to record query/command history
 136
 137 #### New usages
 138 - Vector designing with web tech to replace Adobe Illustrator/Inkscape.
 139   - Design with web tech.
 140
 141   - Printing to pdf with customized paper size.
 142   - Magnify the pdf paper size to the required size.
 143
 144   OR
 145
 146   - Adjust window width and use addressbar command line ":Pdf {}" to export vector graphics.
 147   - Use imageMagick to convert to any other vector graphics format.
 148
 149 #### License
 150 You can copy or modify the code/program under the terms of the GPL3.0 or later versions.