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 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 decompress 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-files]
  45
  46 Later on, you can run "npm install electron" to update electron/chromium or "npm install ebrowser" to update ebrowser independently.
  47
  48 ##### Update app quickly without updating chromium
  49 Pressing "Alt" to show the menu bar and choose "Check for updates" under "Help". OR
  50
  51 Type ":update" in the address bar and press "enter" key to update.
  52
  53 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.
  54
  55 #### Key shortcuts
  56 - Alt: show menu
  57 - ALT+<-: go backward
  58 - ALT+->: go forward
  59 - CTRL+C: stop loading
  60 - CTRL+G: address bar to show page url
  61 - CTRL+L: focus to address bar
  62 - CTRL+T: new Tab
  63 - CTRL+SHIFT+T: restore closed Tab
  64 - CTRL+TAB: switch to next tab
  65 - CTRL+SHIFT+TAB: switch to previous tab
  66 - CTRL+W: close Tab
  67 - CTRL+SHIFT+R: enable global redirection ("gredirect.json")
  68 - CTRL+R: disable global redirection
  69 - ESC: remove focus. similar to vi normal mode.
  70 - F1: Help
  71 - F5: page refresh/reload
  72 - F12: devtools
  73
  74 #### Address bar commands
  75 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:
  76 - "/" for find-in-page
  77 - ":" for address bar commands
  78   - ac [bookmark/history path w/o ext] : load ".rec" file for autocomplete.
  79   - b [bookmarkfilename w/o ext] : bookmark current page in file.
  80   - bjs : Browser-level JavaScript execution.
  81   - bml [filename w/o extension]: load/execute the javascript file.
  82   - cert : allow invalid certificates w/o arguments, otherwise restore to default.
  83   - clear : the arguments could be
  84     - cache : clear cache
  85     - dns : clear dns cache
  86     - storage: clear site storage data.
  87     - {[options](https://www.electronjs.org/docs/latest/api/session#sescleardataoptions)}
  88   - ext [extension path]: load unpacked Chrome extension.
  89   - 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.
  90   - 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.
  91   - nc/uc : No Cookie forwarding/Use Cookie forwarding with global redirection.
  92   - nr/ur for No/Use "redirect.json" for domain redirection.
  93   - np : no proxy.
  94   - 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".
  95   - ua [useragentName] : set user agent for future tabs. default user agent w/o arguments.
  96   - 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).
  97   - 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.
  98 - "!" address bar commands
  99   "!xx ..." evaluates "xx.js" with the whole text as arguments[0].
 100 - i: internal urls, which will be consistent with [uweb](https://jamesfengcao.gitlab.io/uweb/en/links/index.html).
 101   - "i:0/js/xxx.js:[url]" loads the "[url]" with bookmarklet "js/xxx.js".
 102
 103 #### Commands in no-focus mode (this mode is similar to vi Normal mode)
 104 Pressing "ESC" to enter no-focus mode if not sure.
 105 - ":" for address bar commands
 106 - "/" for find-in-page with address bar
 107 - "!" for "!" address bar commands
 108
 109 The other commands are defined in "mapkeys.json", which will map keys to address bar commands.
 110
 111 #### Configuration files
 112 - "config": lines of address bar commands.
 113 - "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.
 114 - "default.autoc": predefined strings for address bar auto completion.
 115 - "gredirect.json": global redirection urls as array of urls
 116 - "redirect.json": domain-replacementDomain pairs, default to be applied.
 117 - "mapkeys.json": keys-addressbarCommands pairs. The addressbar commands are multiple lines of address bar command separated by "\n".
 118 - "proxy.json": name-[ProxyConfig](https://www.electronjs.org/docs/latest/api/structures/proxy-config) pairs
 119 - "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.
 120 - Customized menus: json files as array of strings with menuitem name and address bar commands alternately.
 121   - "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.
 122   - "select.json": to define menus for text selections. The odd-indexed strings are address bar commands with "%s" as the text selection.
 123   - "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.
 124
 125 #### Javascript at three levels
 126 - Web page: url like "javascript:" or bookmarklet command ":bml" runs in web page.
 127 - Browser (or renderer process) :
 128   - ":bjs" to execute the following js code at browser level.
 129   - "!xx" evaluates "xx.js", which could manipulate address bar etc.
 130 - OS level (or main process) : ":js" to execute the following js code with all OS APIs available.
 131
 132 ##### examples for ":js"/":bjs" commands
 133
 134     :js bJS=true //allow external Javascript files for web pages
 135     :js bJS=false //disallow external Javascript files for web pages
 136     :bjs bHistory=true //to record url history
 137     :bjs bQueryHistory=true //to record query/command history
 138
 139 #### New usages
 140 - Vector designing with web tech to replace Adobe Illustrator/Inkscape.
 141   - Design with web tech.
 142
 143   - Printing to pdf with customized paper size.
 144   - Magnify the pdf paper size to the required size.
 145
 146   OR
 147
 148   - Adjust window width and use addressbar command line ":Pdf {}" to export vector graphics.
 149   - Use imageMagick to convert to any other vector graphics format.
 150
 151 #### License
 152 You can copy or modify the code/program under the terms of the GPL3.0 or later versions.