You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Learn how to create custom RSS feeds using html2rss configuration files
4
4
---
5
5
6
-
Want to create RSS feeds for websites that don't offer them? This guide shows you how to write simple configuration files that tell the html2rss engine exactly what content to extract.
6
+
Want to create RSS feeds for websites that don't offer them? This guide shows you how to write simple configuration files.
7
7
8
-
**Don't worry if you're not technical** - we'll explain everything step by step!
8
+
**New to html2rss?** Start with the [web app](/web-application/getting-started) or [browse existing feeds](/feed-directory/) first.
9
9
10
-
You can see examples of what others have created in the [Feed Directory](/feed-directory/).
10
+
---
11
+
12
+
## Quick Start
13
+
14
+
**Need a feed right now?**
15
+
1.**[Try the web app](/web-application/getting-started)** - No coding required
16
+
2.**[Browse ready-made feeds](/feed-directory/)** - Use what others created
17
+
3.**Create a config** - When you need custom control (see below)
18
+
19
+
**Ready to create a config?** Jump to [Your First Config](#your-first-config).
11
20
12
21
---
13
22
14
23
## How It Works
15
24
16
-
Think of the html2rss engine as a smart assistant that needs instructions. You give it a simple "recipe" (called a config file) that tells it:
17
-
25
+
A config file is a simple "recipe" that tells html2rss:
18
26
1.**Which website** to look at
19
-
2.**What content** to find (articles, posts, etc.)
20
-
3.**How to organize** that content into an RSS feed
21
-
22
-
The recipe is written in YAML - a simple format that's easy to read and write. Both html2rss-web and the html2rss Ruby gem use these same configuration files.
27
+
2.**What content** to find
28
+
3.**How to organize** it into an RSS feed
23
29
24
30
### The `channel` Block
25
31
26
-
This tells the html2rss engine basic information about your feed - like giving it a name and telling it which website to look at.
32
+
This tells html2rss basic information about your feed - like giving it a name and telling it which website to look at.
27
33
28
34
**Example:**
29
-
30
35
```yaml
31
36
channel:
32
37
url: https://example.com/blog
@@ -40,7 +45,6 @@ This says: "Look at this website and call the feed 'My Awesome Blog'"
40
45
This is where you tell the html2rss engine exactly what to find on the page. You use CSS selectors (like you might use in web design) to point to specific parts of the webpage.
41
46
42
47
**Example:**
43
-
44
48
```yaml
45
49
selectors:
46
50
items:
@@ -49,135 +53,94 @@ selectors:
49
53
selector: "h2 a"
50
54
link:
51
55
selector: "h2 a"
56
+
attribute: href
52
57
```
53
58
54
-
This says: "Find each article, get the title from the h2 link, and get the link from the same h2 link"
59
+
This says: "Find each article, get the title from the h2 anchor, and get the link from the same h2 anchor's href attribute"
55
60
56
61
**Need more details?** Check our [complete guide to selectors](/ruby-gem/reference/selectors/) for all the options.
57
62
58
63
---
59
64
60
-
## Tutorial: Your First Feed
61
-
62
-
Let's create a simple RSS feed step by step. We'll use a basic blog as our example.
65
+
## Your First Config
63
66
64
-
### Step 1: Look at the Website
67
+
**Step 1:** Look at the website you want to create a feed for. Right-click → "View Page Source" to see the HTML structure.
65
68
66
-
First, visit the website you want to create a feed for. Right-click and "View Page Source" to see the HTML structure. Look for patterns like this:
67
-
68
-
```html
69
-
<div class="posts">
70
-
<article class="post">
71
-
<h2><a href="/post/1">First Post</a></h2>
72
-
<p>This is the summary of the first post.</p>
73
-
</article>
74
-
<article class="post">
75
-
<h2><a href="/post/2">Second Post</a></h2>
76
-
<p>This is the summary of the second post.</p>
77
-
</article>
78
-
</div>
79
-
```
80
-
81
-
**What we see:** Each article is wrapped in `<article class="post">`, titles are in `<h2><a>` tags, and descriptions are in `<p>` tags.
82
-
83
-
### Step 2: Create Your Config File
84
-
85
-
Create a new text file and save it as `my-blog.yml` (or any name you like). Add this basic information:
69
+
**Step 2:** Create a file called `example.com.yml` with this basic structure:
86
70
87
71
```yaml
88
-
# my-blog.yml
89
72
channel:
90
73
url: https://example.com/blog
91
-
title: My Awesome Blog
92
-
description: The latest news from my awesome blog.
93
-
```
94
-
95
-
This tells html2rss: "Look at this website and call the feed 'My Awesome Blog'"
74
+
title: My Blog
96
75
97
-
### Step 3: Tell html2rss What to Find
98
-
99
-
Now add the selectors that tell html2rss exactly what content to extract:
100
-
101
-
```yaml
102
-
# my-blog.yml
103
76
selectors:
104
77
items:
105
78
selector: "article.post"
106
79
title:
107
80
selector: "h2 a"
108
81
link:
109
82
selector: "h2 a"
110
-
description:
111
-
selector: "p"
83
+
attribute: href
112
84
```
113
85
114
-
**What this means:**
86
+
**Step 3:** Test it with the [web app](/web-application/) or [Ruby gem](/ruby-gem/installation).
115
87
116
-
- `items: "article.post"` = "Find each article with class 'post'"
117
-
- `title: "h2 a"` = "Get the title from the h2 link"
118
-
- `link: "h2 a"` = "Get the link from the same h2 link"
119
-
- `description: "p"` = "Get the description from the paragraph"
88
+
**Need help?** See our [detailed tutorial](/ruby-gem/tutorials/your-first-feed/) or [troubleshooting guide](/support/troubleshooting).
120
89
121
90
---
122
91
123
-
## Advanced Techniques
92
+
## Troubleshooting
124
93
125
-
### Dynamic Feeds with Parameters
94
+
**Common issues:**
95
+
- **No items found?** Check your selectors with browser tools (F12)
96
+
- **Invalid YAML?** Use spaces, not tabs
97
+
- **Website not loading?** Check the URL
126
98
127
-
Use the `parameters` block to create flexible configs. This is useful for feeds based on search terms, categories, or regions.
99
+
**Need more help?** See our [troubleshooting guide](/support/troubleshooting) or ask in [GitHub Discussions](https://github.com/orgs/html2rss/discussions).
128
100
129
-
```yaml
130
-
# news-search.yml
131
-
parameters:
132
-
query:
133
-
type: string
134
-
default: "technology"
101
+
---
135
102
136
-
channel:
137
-
url: "https://news.example.com/search?q={query}"
138
-
title: "News results for '{query}'"
103
+
## Advanced Features
139
104
140
-
selectors:
141
-
items:
142
-
selector: ".article"
143
-
title:
144
-
selector: "h2 a"
145
-
url:
146
-
selector: "h2 a"
147
-
extractor: "href"
148
-
```
105
+
**Dynamic parameters, custom headers, and more:** See our [advanced features guide](/ruby-gem/how-to/advanced-features/).
149
106
150
107
---
151
108
152
-
## Contributing Your Config
153
-
154
-
Have you created a config that others might find useful? We strongly encourage you to contribute it to the project! By sharing your config, you make it available to all users of the public `html2rss-web` service and the Feed Directory.
109
+
## Contributing
155
110
156
-
To contribute, please [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) to the `html2rss-configs` repository.
111
+
**Share your config withthe community:**
157
112
158
-
---
113
+
1. Go to [html2rss-configs on GitHub](https://github.com/html2rss/html2rss-configs)
3. Paste your config → "Commit new file" → "Open pull request"
159
116
160
-
## Usage and Integration
117
+
**Need help?** See our [contribution guide](https://github.com/html2rss/html2rss-configs/blob/main/CONTRIBUTING.md).
161
118
162
-
### With `html2rss-web`
119
+
---
163
120
164
-
Once your pull request is reviewed and merged, your config will become available on the public [`html2rss-web`](/web-application/) instance. You can then access it at the path `/<domainname.tld/path>.rss`.
121
+
## Next Steps
165
122
166
-
### Programmatic Usage in Ruby
123
+
**🎉 Congratulations!** You've learned the basics of creating html2rss configuration files.
167
124
168
-
You can also use `html2rss-configs` programmatically in your Ruby applications.
125
+
### What's Next?
169
126
170
-
Add this to your Gemfile:
127
+
**For Beginners:**
128
+
- **[Browse the Feed Directory](/feed-directory/)** - See real-world examples
129
+
- **[Try html2rss-web](/web-application/getting-started)** - Create feeds without coding
130
+
- **[Learn more about selectors](/ruby-gem/reference/selectors/)** - Master CSS selectors
Copy file name to clipboardExpand all lines: src/content/docs/index.mdx
+21-15Lines changed: 21 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,31 +5,37 @@ description: "html2rss brings back RSS. It is an open source project with decent
5
5
6
6
Ever wished you could follow your favorite websites like a social media feed? The html2rss project makes it possible by creating RSS feeds for any website - even ones that don't offer them.
7
7
8
-
[**🚀 Get Started with html2rss-web**](/web-application/getting-started)
9
-
10
8
---
11
9
12
-
## What is RSS?
10
+
## Why Use RSS Feeds?
11
+
12
+
Instead of visiting 20 different websites every day, you can:
13
13
14
-
RSS (Really Simple Syndication) lets you follow websites in your favorite feed reader. Instead of checking multiple websites daily, you get all updates in one place - like a personalized news feed.
14
+
-**Get all updates in one place** - your feed reader
15
+
-**Never miss new content** - automatic notifications
16
+
-**Save time** - no more manual checking
17
+
-**Stay organized** - categorize and filter content
15
18
16
-
## The html2rss Project
19
+
---
17
20
18
-
The html2rss project provides two main ways to create RSS feeds:
21
+
## What is html2rss?
19
22
20
-
-**html2rss-web** - A user-friendly web application (recommended for most users)
21
-
-**html2rss** - A Ruby gem for developers and advanced users
23
+
html2rss is a user-friendly web application that turns any website into an RSS feed. Think of it as a translator that converts website content into a format your feed reader can understand.
22
24
23
-
Both use the same powerful engine to extract content from websites and convert it into RSS feeds.
25
+
**Two ways to use html2rss:**
26
+
-**html2rss-web** - Easy-to-use web application (recommended for most users)
27
+
-**html2rss Ruby gem** - For developers and advanced users
24
28
25
29
---
26
30
27
-
## Choose Your Path
31
+
## Quick Start
28
32
29
-
-**[html2rss-web](/web-application):****Start here!** Easy-to-use web application. No technical knowledge required.
30
-
-**[Feed Directory](/feed-directory/):**Browse ready-made feeds for popular websites
31
-
-**[html2rss (Ruby Gem)](/ruby-gem):**For developers who want to create custom configurations
33
+
**Option 1: Browse Ready-Made Feeds (Easiest)**
34
+
1.**[Feed Directory](/feed-directory/)**- See what's already available
35
+
2.**Copy the RSS URL**and add it to your feed reader
32
36
33
-
---
37
+
**Option 2: Create Your Own Feeds**
38
+
1.**[Try html2rss-web](/web-application/getting-started)** - No technical knowledge required
39
+
2.**[Install your own instance](/web-application/installation)** - For advanced users
34
40
35
-
**Ready to get started?**Check out our [html2rss-web getting started guide](/web-application/getting-started) or [browse existing feeds](/feed-directory/) to see what's possible.
41
+
**New to RSS?**Start with the [Feed Directory](/feed-directory/) to see examples, then try [html2rss-web](/web-application/getting-started) to create your own feeds.
Copy file name to clipboardExpand all lines: src/content/docs/ruby-gem/reference/channel.mdx
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,3 +27,7 @@ channel:
27
27
| `ttl` | Optional | The "time to live" for the feed in minutes. Defaults to the `max-age` from the response headers, or `360`. |
28
28
| `language` | Optional | The language of the feed. Defaults to the `lang` attribute of the `<html>` tag. |
29
29
| `time_zone` | Optional | The time zone for parsing dates. See the [list of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). |
30
+
31
+
---
32
+
33
+
For detailed documentation on the Ruby API, see the [official YARD documentation](https://www.rubydoc.info/gems/html2rss).
Copy file name to clipboardExpand all lines: src/content/docs/ruby-gem/reference/headers.mdx
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,3 +19,7 @@ headers:
19
19
## Dynamic Parameters
20
20
21
21
You can also use dynamic parameters in your headers to pass values at runtime. See [Dynamic Parameters](/ruby-gem/how-to/dynamic-parameters) for more information.
22
+
23
+
---
24
+
25
+
For detailed documentation on the Ruby API, see the [official YARD documentation](https://www.rubydoc.info/gems/html2rss).
0 commit comments