20 | Parse a URL or HTML string into a structured article using [@mozilla/readability](https://github.com/@mozilla/readability). 21 | - **WKWebView Integration**
22 | Easily integrate with WKWebView. 23 | - **Reader Mode Overlay**
24 | Easily toggle a reader overlay with customizable themes and font sizes. 25 | 26 | ## Requirements 27 | 28 | - **Swift:** 6.0 or later 29 | - **Xcode:** 16.0 or later 30 | 31 | ## Installation 32 | swift-readability is available via the Swift Package Manager 33 | ```Swift 34 | .package(url: "https://github.com/Ryu0118/swift-readability", exact: "0.1.0") 35 | ``` 36 | 37 | ## Usage 38 | ### Basic Parsing 39 | You can parse an article either from a URL or directly from an HTML string.
40 | 41 | Parsing from a URL: 42 | ```swift 43 | import Readability 44 | 45 | let readability = Readability() 46 | let result = try await readability.parse(url: URL(string: "https://example.com/article")!) 47 | ``` 48 | 49 | Parsing from an HTML string: 50 | ```swift 51 | import Readability 52 | 53 | let html = """ 54 | 55 | 56 | 57 | """ 58 | let result = try await readability.parse(html: html) 59 | ``` 60 | 61 | ### Implementing Reader Mode with WKWebView 62 | swift-readability provides `ReadabilityWebCoordinator` that prepares a `WKWebView` configuration, and exposes two asynchronous streams: `contentParsed` (emitting generated reader HTML) and `availabilityChanged` (emitting reader mode availability updates). This configuration enables your `WKWebView` to detect when a web page is suitable for reader mode, generate a reader-friendly HTML overlay, and toggle reader mode dynamically. 63 | 64 | ```swift 65 | import ReadabilityUI 66 | 67 | let coordinator = ReadabilityWebCoordinator(initialStyle: ReaderStyle(theme: .dark, fontSize: .size5)) 68 | let configuration = try await coordinator.createReadableWebViewConfiguration() 69 | let webView = WKWebView(frame: .zero, configuration: configuration) 70 | 71 | // Process generated reader HTML asynchronously. 72 | for await html in coordinator.contentParsed { 73 | do { 74 | try await webView.showReaderContent(with: html) 75 | } catch { 76 | // Handle the error here. 77 | } 78 | } 79 | 80 | // Monitor reader mode availability asynchronously. 81 | for await availability in coordinator.availabilityChanged { 82 | // For example, update your UI to enable or disable the reader mode button. 83 | } 84 | ``` 85 | 86 | ### ReaderControllable Protocol 87 | 88 | Below are usage examples for each of the functions provided by the `ReaderControllable` protocol extension. Since `WKWebView` conforms to `ReaderControllable`, you can call these methods directly on your `WKWebView` instance. 89 | 90 | > [!WARNING] 91 | > Changes to the reader style (theme and font size) are only available when the web view is in Reader Mode. 92 | 93 | ```swift 94 | import ReadabilityUI 95 | 96 | // Set the entire reader style (theme and font size) 97 | try await webView.set(style: ReaderStyle(theme: .dark, fontSize: .size5)) 98 | 99 | // Set only the reader theme (supports sepia, light, and dark). 100 | try await webView.set(theme: .sepia) 101 | 102 | // Set only the font size 103 | try await webView.set(fontSize: .size7) 104 | 105 | // Show the reader overlay using the HTML received from the ReadabilityWebCoordinator.contentParsed(_:) event. 106 | try await webView.showReaderContent(with: html) 107 | 108 | // Hide the reader overlay. 109 | try await webView.hideReaderContent() 110 | 111 | // Determine if the web view is currently in reader mode. 112 | let isReaderMode = try await webView.isReaderMode() 113 | ``` 114 | 115 | If you are using a SwiftUI wrapper library for WKWebView (such as [Cybozu/WebUI](https://github.com/cybozu/WebUI)) that does not expose the WKWebView instance, you can conform any object that has an evaluateJavaScript method to ReaderControllable. For example: 116 | ```swift 117 | import WebUI 118 | import ReadabilityUI 119 | 120 | extension WebViewProxy: @retroactive ReaderControllable { 121 | public func evaluateJavaScript(_ javascriptString: String) async throws -> Any { 122 | let result: Any? = try await evaluateJavaScript(javascriptString) 123 | return result ?? () 124 | } 125 | } 126 | ``` 127 | By conforming `WebViewProxy` to `ReaderControllable`, you can control the reader from the proxy, for example: 128 | ```swift 129 | WebViewReader { proxy in 130 | WebView(configuration: configuration) 131 | .task { 132 | for await html in coordinator.contentParsed { 133 | if let url = proxy.url { 134 | try? await proxy.showReaderContent(with: html) 135 | try? await proxy.set(theme: .dark) 136 | try? await proxy.set(fontSize: .size8) 137 | } 138 | } 139 | } 140 | } 141 | ``` 142 | 143 | ## Example (Integrating with SwiftUI) 144 | For a more detailed implementation of integrating swift-readability with SwiftUI using [Cybozu/WebUI](https://github.com/cybozu/WebUI), please refer to the [Example](./Example) provided in this repository. 145 | 146 | ## Build 147 | Before building the Swift Package, please complete the following steps: 148 | 1. Verify that npm is installed. 149 | 2. Then, run `make bootstrap`. 150 | 151 |
If you modify the source code in the webpack-resources folder, please run `npm run build` 152 | 153 | ## Credits 154 | This project leverages several open source projects: 155 | 156 | - [@mozilla/readability](https://github.com/mozilla/readability) for parsing web pages and generating reader-friendly content (licensed under the MIT License). 157 | - [mozilla-mobile/firefox-ios](https://github.com/mozilla-mobile/firefox-ios) for inspiration on Reader Mode functionality (licensed under the MPL 2.0). 158 | - [Cybozu/WebUI](https://github.com/Cybozu/WebUI) for the SwiftUI integration example (licensed under the MIT License). 159 | - [cure53/DOMPurify](https://github.com/cure53/DOMPurify) for sanitizing HTML content (licensed under the MIT License). 160 | 161 | In addition, the following files are distributed under the Mozilla Public License, Version 2.0 (MPL 2.0): 162 | - [webpack-resources/AtDocumentStart.js](./webpack-resources/AtDocumentStart.js) 163 | - [webpack-resources/ReadabilitySanitized.js](./webpack-resources/ReadabilitySanitized.js) 164 | - [webpack-resources/Reader.html](./webpack-resources/Reader.html) 165 | - [webpack-resources/Reader.css](./webpack-resources/Reader.css) 166 | - [Sources/ReadabilityUI/Resources/AtDocumentStart.js](./Sources/ReadabilityUI/Resources/AtDocumentStart.js) 167 | - [Sources/ReadabilityUI/Resources/Reader.html](./Sources/ReadabilityUI/Resources/Reader.html) 168 | - [Sources/Readability/Resources/ReadabilitySanitized.js](./Sources/Readability/Resources/ReadabilitySanitized.js) 169 | - [Sources/ReadabilityCore/ReaderStyle.swift](./Sources/ReadabilityCore/ReaderStyle.swift) 170 | -------------------------------------------------------------------------------- /Sources/Readability/Internal/HTMLFetcher.swift: -------------------------------------------------------------------------------- 1 | import Foundation 2 | 3 | struct HTMLFetcher { 4 | enum Error: LocalizedError { 5 | case noValidEncodingFound 6 | 7 | var errorDescription: String? { 8 | switch self { 9 | case .noValidEncodingFound: 10 | "No valid encoding found" 11 | } 12 | } 13 | } 14 | 15 | private let session = URLSession.shared 16 | 17 | func fetch(url: URL) async throws -> String { 18 | let (htmlData, _) = try await URLSession.shared.data(from: url) 19 | let encodings: [String.Encoding] = [ 20 | .utf8, 21 | .shiftJIS, 22 | .ascii, 23 | .utf16, 24 | .utf16LittleEndian, 25 | .utf32, 26 | .utf32LittleEndian, 27 | .isoLatin1, 28 | .japaneseEUC, 29 | .windowsCP1250, 30 | .windowsCP1251, 31 | .windowsCP1252, 32 | ] 33 | 34 | var html: String? 35 | for encoding in encodings { 36 | if let string = String(data: htmlData, encoding: encoding) { 37 | html = string 38 | break 39 | } 40 | } 41 | 42 | guard let html else { 43 | throw Error.noValidEncodingFound 44 | } 45 | 46 | return html 47 | } 48 | } 49 | -------------------------------------------------------------------------------- /Sources/Readability/Internal/ReadabilityRunner.swift: -------------------------------------------------------------------------------- 1 | import ReadabilityCore 2 | import SwiftUI 3 | import WebKit 4 | 5 | /// A runner class responsible for processing HTML content and producing a `ReadabilityResult`. 6 | /// This class uses a WKWebView to load HTML and execute JavaScript for parsing. 7 | @MainActor 8 | final class ReadabilityRunner { 9 | private let webView: WKWebView 10 | 11 | // The message handler that listens for events from the injected JavaScript. 12 | private weak var messageHandler: ReadabilityMessageHandler
751 |
754 |
755 | %READER-TITLE%
752 |%READER-BYLINE%
753 |
756 | %READER-CONTENT%
757 |
758 |
759 |
760 |
761 |
762 |
--------------------------------------------------------------------------------
/Sources/ReadabilityUI/exported.swift:
--------------------------------------------------------------------------------
1 | @_exported import ReadabilityCore
2 |
--------------------------------------------------------------------------------
/Tests/ReadabilityTests/ReadabilityTests.swift:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Ryu0118/swift-readability/5baf9d1fddc66fae9be962462532a27269882f93/Tests/ReadabilityTests/ReadabilityTests.swift
--------------------------------------------------------------------------------
/bootstrap.sh:
--------------------------------------------------------------------------------
1 | if ! command -v nest >/dev/null 2>&1; then
2 | curl -s https://raw.githubusercontent.com/mtj0928/nest/main/Scripts/install.sh | bash
3 | fi
4 |
5 | ~/.nest/bin/nest bootstrap nestfile.yaml
6 |
7 | npm install
8 | npm run build
9 |
--------------------------------------------------------------------------------
/nestfile.yaml:
--------------------------------------------------------------------------------
1 | nestPath: ./.nest
2 | targets:
3 | - reference: nicklockwood/SwiftFormat
4 | version: 0.55.5
5 | assetName: swiftformat.artifactbundle.zip
6 | checksum: 2c6e8903b88ca94f621586a91617c89337f53460bb3db00e3de655f96895a1a8
7 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "dependencies": {
3 | "@mozilla/readability": "^0.5.0",
4 | "dompurify": "^3.2.3"
5 | },
6 | "devDependencies": {
7 | "html-webpack-plugin": "^5.6.3",
8 | "raw-loader": "^4.0.2",
9 | "webpack": "^5.97.1",
10 | "webpack-cli": "^6.0.1"
11 | },
12 | "scripts": {
13 | "build": "./node_modules/.bin/webpack -c webpack.config.js"
14 | }
15 | }
16 |
--------------------------------------------------------------------------------
/webpack-resources/AtDocumentStart.js:
--------------------------------------------------------------------------------
1 | /* This Source Code Form is subject to the terms of the Mozilla Public
2 | * License, v. 2.0. If a copy of the MPL was not distributed with this file,
3 | * You can obtain one at http://mozilla.org/MPL/2.0/.
4 | */
5 |
6 | "use strict";
7 | import { isProbablyReaderable, Readability } from "@mozilla/readability";
8 |
9 | // Debug flag to control logging.
10 | const DEBUG = false;
11 |
12 | // Variables to hold the readability result, current style, and original body style.
13 | let readabilityResult = null;
14 | let currentStyle = null;
15 | let originalBodyStyle = null;
16 |
17 | const themeColors = {
18 | light: { background: "#ffffff", color: "#15141a" },
19 | dark: { background: "#333333", color: "#fbfbfe" },
20 | sepia: { background: "#fff4de", color: "#15141a" }
21 | };
22 |
23 | // Selector for block-level images in the content.
24 | const BLOCK_IMAGES_SELECTOR =
25 | ".content p > img:only-child, " +
26 | ".content p > a:only-child > img:only-child, " +
27 | ".content .wp-caption img, " +
28 | ".content figure img";
29 |
30 | /**
31 | * Logs debug information if DEBUG is enabled.
32 | * @param {*} s - The message or object to log.
33 | */
34 | function debug(s) {
35 | if (!DEBUG) {
36 | return;
37 | }
38 | console.log(s);
39 | }
40 |
41 | /**
42 | * Checks if the current document is readerable and initiates parsing if so.
43 | */
44 | function checkReadability() {
45 | setTimeout(function() {
46 | if (!isProbablyReaderable(document)) {
47 | postStateChangedToUnavailable();
48 | return;
49 | }
50 |
51 | if ((document.location.protocol === "http:" || document.location.protocol === "https:") &&
52 | document.location.pathname !== "/") {
53 | // If a previous readability result exists, reuse it.
54 | if (readabilityResult && readabilityResult.content) {
55 | postStateChangedToAvailable();
56 | postContentParsed(readabilityResult);
57 | return;
58 | }
59 |
60 | const uri = {
61 | spec: document.location.href,
62 | host: document.location.host,
63 | prePath: document.location.protocol + "//" + document.location.host,
64 | scheme: document.location.protocol.substr(0, document.location.protocol.indexOf(":")),
65 | pathBase: document.location.protocol + "//" + document.location.host + location.pathname.substr(0, location.pathname.lastIndexOf("/") + 1)
66 | };
67 |
68 | const docStr = new XMLSerializer().serializeToString(document);
69 | if (docStr.indexOf("