{"id":16801963,"url":"https://github.com/shivaprsd/doq","last_synced_at":"2025-03-17T03:31:11.697Z","repository":{"id":39967012,"uuid":"321905802","full_name":"shivaprsd/doq","owner":"shivaprsd","description":"The missing reader mode/color schemes tool for PDFs. 👓","archived":false,"fork":false,"pushed_at":"2024-11-25T19:49:27.000Z","size":1316,"stargazers_count":40,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-16T07:51:08.939Z","etag":null,"topics":["color-schemes","dark-mode","es6-module","eye-comfort","pdf","pdfjs","reader-mode"],"latest_commit_sha":null,"homepage":"https://shivaprsd.github.io/doq/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shivaprsd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-16T07:39:37.000Z","updated_at":"2025-03-13T08:16:01.000Z","dependencies_parsed_at":"2024-08-01T12:47:54.388Z","dependency_job_id":"a0a14dcc-43f3-42c5-b152-ef7094412ff6","html_url":"https://github.com/shivaprsd/doq","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shivaprsd%2Fdoq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shivaprsd%2Fdoq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shivaprsd%2Fdoq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shivaprsd%2Fdoq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shivaprsd","download_url":"https://codeload.github.com/shivaprsd/doq/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243968834,"owners_count":20376455,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["color-schemes","dark-mode","es6-module","eye-comfort","pdf","pdfjs","reader-mode"],"created_at":"2024-10-13T09:38:18.363Z","updated_at":"2025-03-17T03:31:11.393Z","avatar_url":"https://github.com/shivaprsd.png","language":"JavaScript","readme":"![doq logo](docs/logo/logo.png)\n\n# doq\n\n*doq* (pronounced as *doc-HUE*) is an add-on for Mozilla's excellent\n[PDF.js][1] PDF viewer.\n\nIt adds a **reader mode** where you can change the *colors* of the rendered PDF\nfiles, to make it more comfortable to the eyes while reading. It works similar\nto the reader mode in web browsers and theme options in eBook readers (except\nthat it cannot change the fonts or reflow text).\n\n*doq* was inspired by Safari's Reader View, and many terminal color schemes.\n\n![Screenshot with a light theme applied](docs/screenshots/reader-light.png)\n\n![Screenshot with a dark theme applied](docs/screenshots/reader-dark.png)\n\n## Usage\n\nIf you simply want to use *doq* to read PDFs, try [*doqment*][6]. It is a\nbrowser extension that bundles *doq* with PDF.js and opens all your PDF links.\nYou can skip the rest of this section.\n\n*doq* is written as a native [ES6 module][2]; there is no bundled version.\nHence it runs only in modern browsers that supports `import` and `export`.\n\n### Installation\n\nFor your own deployment of the PDF.js viewer:\n\n1. [Download][3] the latest version (or clone this repo)\n2. Copy the `addon/` and `lib/` directories to some directory on your server\\\n   (e.g. `/pdfjs-dist/addons/doq/`)\n3. Include `addon/doq.js` as a module in the `viewer.html` of your deployment:\n\n```js\n\u003cscript type=\"module\" src=\"/path/to/addon/doq.js\"\u003e\u003c/script\u003e\n```\n4. The global add-on object can be accessed later as `window.DOQ`.\n\nAlternatively, to simply import as an ES6 module:\n`import doq from \"path/to/lib/doq.js\"`.\n\nPlease check the exported functions of `lib/api.js` for the API for both the\nglobal add-on object and the module import.\n\nThe add-on targets the default generic viewer of PDF.js. It should also work in\ncustom viewers built on top of that. Feel free to open an issue if it breaks in\nyour viewer.\n\n### Defining colors\n\nColor schemes are defined in `lib/colors.json`, which you can extend. Only\n6-digit RGB hex codes are currently supported.\n\nEach color scheme can have up to *three* tones. `background` and `foreground`\nwill replace the white and black colors in the document respectively; they also\ndefine the gradient to which the rest of the greyscale gets interpolated. Other\ncolors map to their nearest color among `accents`, which can be specified per\ntone and/or per scheme. They too get mapped to the gradient if no `accents` are\nsupplied.\n\nIncluded by default are the Firefox, Safari Reader View themes and the\n[Solarized][4] color scheme.\n\n### Reader options\n\nDeployments can configure the following options by writing key-value pairs\ndirectly to `doq.options` in Local storage (example follows):\n\n- `autoReader` [Boolean]: Whether to automatically apply the last-used reader\n  theme at launch. Default `true`.\n- `dynamicTheme` [Boolean]: Whether to save separate last-used preferences for\n  OS light/dark themes. Default `true`.\n\n```js\n/* Options have to be set before loading doq */\nconst doqOptions = { dynamicTheme: false };\nlocalStorage.setItem(\"doq.options\", JSON.stringify(doqOptions));\n```\n\n## Features\n\n![Screenshot of the doq toolbar](docs/screenshots/addon-toolbar.png)\n\n- **Reader mode**: applies the selected theme to the document's background,\n  text and (optionally) to lines and other shapes.\n\n- **Blend images**: make images in the document blend with the new background\n  (or text color in the case of dark themes).\n\n- **Invert mode**: to simply invert the (original) document colors if that is\n  all you need (and you don't mind negative images).\n\n- **Intelligent application**: *doq* does not blindly change text color, but\n  tries to ensure the legibility of the text against the background in which it\n  is rendered.\n\n- **Color-science aware**: *doq* does color transformations in the\n  perceptually-uniform [CIELAB color space][5].\n\n- **Accessibility**: the add-on toolbar is designed, following WCAG guidelines,\n  to be well accessible to keyboard/screen-reader users.\n\n- **Remember preferences**: *doq* loads the last used settings at launch, and\n  also updates them dynamically, based on the OS theme in use.\n\n### Performance\n\n*doq* recalculates the colors when the page is being rendered by PDF.js. This\nincurs a small overhead, slightly reducing the renderer's performance. *doq*\ntries to minimize this overhead with many optimizations (like caching the\ncalculation results) so that speed improves after the initial render. External\nbenchmark tests are welcome.\n\nThis does not apply to the quick-invert mode as no processing is done there; it\nis implemented as a simple CSS filter, and hence, is fast.\n\n(I guess this can be avoided altogether by implementing the logic directly\nwithin the PDF.js library by modifying the source. But that requires digging\ninto PDF.js internals and also building and testing the entire thing, which I\nhave zero experience with. Hence I chose the add-on route.)\n\n## Why *doq*?\n\nSame reason that led Ethan Schoonover in developing the Solarized color scheme:\n**ergonomics for eyes**. It is best summarized by this quote from the Solarized\nReadme:\n\n\u003e Black text on white from a computer display is akin to reading a book in\n\u003e direct sunlight and tires the eye.\n\nPDFs are perhaps the single largest source of \"black text on white\" out there\n*that are not amenable to modification*. Designed to look the same everywhere,\nthe PDF format, unlike EPUB or plain text, does not offer the flexibility of\nchoosing its appearance while viewing. Yet it is the most popular document\nformat in existence. Not much talk about ergonomics.\n\nAnother point is **accessibility**. The ability to adjust the colors of\ndocuments can be immensly helpful to people with color vision deficiencies or\nother low-vision conditions. Document creators are usually *blind* to such\nconcerns.\n\nThe Web is heeding the call, with major browsers now having reader modes, and\nmore and more websites providing dark/night/low-contrast versions on their own.\nBut I could find scarcely any efforts in that direction in the domain of PDF\nviewing. None of the viewers I tried offered any simple way to change the PDF's\nappearance. In the end I decided to create a tool on my own.\n\n### OK, but why *PDF.js*?\n\nPerhaps a web app is still not the best tool to view a PDF document; but they\nseem to be getting there. With modern browsers, PDF.js does a decent job, and\nis FireFox's built-in PDF viewer. Being familiar with web and JS, I saw it as\nthe tool that I could quickly extend and develop my solution for, without\nneeding to pore over thousands of lines of code of a low-level PDF library. It\nrequires no additional software and is automatically cross-platform, meaning I\ncould have my solution immediately available on my smartphone also, without\nmuch additional coding.\n\nThe limitations do bug me sometimes. I would be delighted to see a *doq*-like\nfeature added to other popular PDF viewers also. I plan to work towards that\ngoal in future if time permits.\\\n*Eye ergonomics matter.*\n\nSuggestions and contributions are welcome!\n\n---\n\nThis project started out slightly differently; versions 1.x are now legacy. If\ninterested, see v2.0 release notes for an overview of what changed, and why.\n\n[1]: https://mozilla.github.io/pdf.js/\n[2]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules\n[3]: https://github.com/shivaprsd/doq/releases/latest\n[4]: https://ethanschoonover.com/solarized/\n[5]: https://en.wikipedia.org/wiki/CIELAB_color_space\n[6]: https://github.com/shivaprsd/doqment\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshivaprsd%2Fdoq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshivaprsd%2Fdoq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshivaprsd%2Fdoq/lists"}