jekyll-devto 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5de7210b54c1eeda3f3930fd529ab2acb06d08578b098be5b0bcc9389f2decbb
-  data.tar.gz: af15eb800bd515a2554b93c431a054edabc161883108301e6f542d10eefa0d43
+  metadata.gz: e5d68c73dff2c64c76de9bd3e8fc0d9e130d89cc9abc0f49473b69ce4d55a2e3
+  data.tar.gz: 791dfd16298f0b7d0ca0126594419a812fc3a84aa3da46e0c8da7690a6a45c0a
 SHA512:
-  metadata.gz: 6bf236df31a78ac816447e7fc62f5424cf369e4e1f94287b618e18b16ca15e18e6f629b11b62313e046f8e808ffe4d45bf792ae61979c5c64e96345229ce27d0
-  data.tar.gz: e30ab831596ed0880e33bac1eeec3874adf4da9fe2670a67cbc48dc215366fc34955f315f6d92d48ec7175424106d7d4450a41a81591b59efbad465ec74b03a5
+  metadata.gz: 38c78047e58a1557a7327d3b95104342bf5920ce365dfb3ea3c8665227ab83297c0c9bed6dd0e30ea1a499e5af28d8b7b7fcc24374c5e234384dec4116c722c2
+  data.tar.gz: 92cc3df16600b846a8a08868033f54e051e7415d747671a0e88e730c95f7e220e942eb14b3be61700e181a08a220db23ec9ea4836140b1cc07220c674231d3d4

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.3.0](https://github.com/JuanVqz/jekyll-devto/compare/v0.2.0...v0.3.0) (2026-10-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* **feed:** posts no longer get their image as the dev.to cover by default. Set devto: { cover: image } in _config.yml to keep the 0.2.0 behavior.
+
+### Features
+
+* **feed:** add a dev.to cover only when asked for ([#14](https://github.com/JuanVqz/jekyll-devto/issues/14)) ([9e9b43f](https://github.com/JuanVqz/jekyll-devto/commit/9e9b43f9422cee3ef4fd7a47aa483347bf5bfde8))
+
+## [0.2.0](https://github.com/JuanVqz/jekyll-devto/compare/v0.1.0...v0.2.0) (2026-10-02)
+
+
+### Features
+
+* choose dev.to tags and series from the post's front matter ([#13](https://github.com/JuanVqz/jekyll-devto/issues/13)) ([1aa48f7](https://github.com/JuanVqz/jekyll-devto/commit/1aa48f7a362781f660a54d6e041f043db5a11eb8))
+* **html:** bring code block languages to dev.to ([#11](https://github.com/JuanVqz/jekyll-devto/issues/11)) ([2e62edb](https://github.com/JuanVqz/jekyll-devto/commit/2e62edb47809cc945af3988973e6c44ad9fe2a27))
+* **publisher:** use the post image as the dev.to cover ([#12](https://github.com/JuanVqz/jekyll-devto/issues/12)) ([90707e7](https://github.com/JuanVqz/jekyll-devto/commit/90707e71fbaa5d309bed29ddc455c04bea07237d))
+
+
+### Documentation
+
+* add gem version and CI badges to the README ([#8](https://github.com/JuanVqz/jekyll-devto/issues/8)) ([a0d2a9c](https://github.com/JuanVqz/jekyll-devto/commit/a0d2a9c47a871597bd4d3f4c1ac113c18b41a323))
+
 ## 0.1.0 (2026-10-01)
 
 

data/README.md

@@ -1,5 +1,8 @@
 # jekyll-devto
 
+[![Gem Version](https://badge.fury.io/rb/jekyll-devto.svg)](https://badge.fury.io/rb/jekyll-devto)
+[![CI](https://github.com/JuanVqz/jekyll-devto/actions/workflows/ci.yml/badge.svg)](https://github.com/JuanVqz/jekyll-devto/actions/workflows/ci.yml)
+
 Cross-post a Jekyll blog to [dev.to](https://dev.to), complete, through dev.to's own RSS import.
 
 dev.to can import posts from your feed, but with a typical Jekyll feed you get:
@@ -46,10 +49,29 @@ All optional.
 devto:
   path: "/devto.xml" # where the feed is written
   limit: 20          # newest posts to include (default: all)
+  cover: image       # use each post's image as its dev.to cover (default: no cover)
 ```
 
 To keep a post off dev.to, set `devto: false` in its front matter.
 
+**Cover image.** No cover by default. Many Open Graph images, including the ones [jekyll-og-image](https://github.com/igor-alexandrov/jekyll-og-image) and Chirpy produce, already carry the post title, which dev.to shows right under the cover, and without a cover dev.to generates its own share image. To add one:
+
+- `devto_cover:` on a post sets that post's cover, and always wins. `devto_cover: true` uses the post's `image`, and `devto_cover: false` turns the cover off for that post.
+- `cover: image` under `devto:` in `_config.yml` uses each post's `image` (a path, a URL, or `{ path: ... }`) for every post, for sites whose images have no title on them.
+
+```yaml
+devto_cover: /assets/img/devto-cover.png # optional, per post
+```
+
+`jekyll-devto publish` adds the cover to the draft; a cover already set on the dev.to draft is kept. dev.to crops covers to 1000×420.
+
+**Tags and series.** dev.to keeps only the first four tags, as lowercase letters and digits (`tailwind-css` becomes `tailwindcss`). `devto_tags` picks them for dev.to; it is used for the import and also replaces the tags of a draft that was already imported. `devto_series` puts the post in a dev.to series, created if it does not exist; a series already set on the draft is kept.
+
+```yaml
+devto_tags: [ruby, rails, jekyll, opensource]
+devto_series: "Rails upgrades"
+```
+
 ## Publishing the drafts
 
 ```sh
@@ -89,9 +111,9 @@ Checked against [Forem's source](https://github.com/forem/forem), the software d
 - **The imported body says `published: false` in its own front matter**, and that wins over the
   API's `published` field (`Article#evaluate_front_matter`). The publish command flips it inside the
   body. A plain `published: true` request leaves the post a draft.
-- **Code blocks arrive without a language.** dev.to removes every `class` attribute before
-  converting (`Feeds::CleanHtml`), so syntax highlighting is lost on import whatever the feed says.
-- **Only the first four tags are kept**, stripped to letters and digits.
+- **The import drops the language of every code block.** dev.to removes every `class` attribute before converting (`Feeds::CleanHtml`), so a fence never gets a language from the feed. The feed marks each block with `data-lang`, which survives, and `jekyll-devto publish` writes that language into the draft's fences, matching blocks by their first line of code.
+- **Sometimes the import keeps the raw HTML instead of Markdown.** dev.to converts the feed only when block tags outnumber blank lines (`Feeds::AssembleArticleMarkdown#html_content?`). The feed removes blank lines between tags and writes newlines inside code as `
`, so every post takes the Markdown path. Drafts imported before this change may still be raw HTML; their code keeps no language.
+- **Only the first four tags are kept**, stripped to letters and digits and lowercased. Use `devto_tags` to choose them.
 - **"Replace self-referential links with DEV-specific links"** rewrites links between your posts to
   their dev.to articles at import time, drafts included. Publish the linked post first, or leave
   that option off.

data/lib/jekyll/devto/feed.xml

@@ -2,9 +2,10 @@
 {%- assign devto = site.devto | default: empty -%}
 {%- comment -%} Not site.url + baseurl: links in content already carry baseurl (relative_url adds it). {%- endcomment -%}
 {%- assign site_url = site.url -%}
+{%- assign site_root = site.url | append: site.baseurl -%}
 {%- assign posts = site.posts | where_exp: "post", "post.devto != false" -%}
 {%- if devto.limit %}{% assign posts = posts | slice: 0, devto.limit %}{% endif %}
-<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom">
+<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:devto="https://github.com/JuanVqz/jekyll-devto">
   <channel>
     <title>{{ site.title | default: site.name | xml_escape }}</title>
     <link>{{ "/" | absolute_url }}</link>
@@ -21,11 +22,39 @@
       <link>{{ post_url }}</link>
       <guid isPermaLink="true">{{ post_url }}</guid>
       <pubDate>{{ post.date | date_to_rfc822 }}</pubDate>
-    {%- assign tags = post.tags | default: post.categories %}
+    {%- comment -%} devto_tags first, so new imports already carry the tags chosen for dev.to. {%- endcomment -%}
+    {%- assign devto_tags = post.devto_tags | devto_list %}
+    {%- assign tags = devto_tags | default: post.tags | default: post.categories %}
     {%- for tag in tags %}
       <category>{{ tag | xml_escape }}</category>
     {%- endfor %}
       <description>{{ post.description | default: post.excerpt | strip_html | strip_newlines | truncatewords: 60 | xml_escape }}</description>
+    {%- comment -%}
+      The dev.to cover is opt-in: many Open Graph images carry the post title, which dev.to
+      already shows under the cover, and without one dev.to generates its own share image.
+      devto_cover on a post always wins (false turns it off, true uses the post image);
+      `devto: { cover: image }` in _config.yml uses each post's image. Unlike content
+      links, image paths leave baseurl out (Chirpy and jekyll-og-image add it when
+      rendering), so the cover needs it.
+    {%- endcomment -%}
+    {%- assign cover = "" %}
+    {%- if post.devto_cover == false %}
+    {%- elsif post.devto_cover == true %}
+      {%- assign cover = post.image | devto_url: site_root %}
+    {%- elsif post.devto_cover %}
+      {%- assign cover = post.devto_cover | devto_url: site_root %}
+    {%- elsif devto.cover == "image" or devto.cover == true %}
+      {%- assign cover = post.image | devto_url: site_root %}
+    {%- endif %}
+    {%- if cover != "" %}
+      <devto:cover>{{ cover | xml_escape }}</devto:cover>
+    {%- endif %}
+    {%- if devto_tags %}
+      <devto:tags>{{ devto_tags | join: "," | xml_escape }}</devto:tags>
+    {%- endif %}
+    {%- if post.devto_series %}
+      <devto:series>{{ post.devto_series | xml_escape }}</devto:series>
+    {%- endif %}
       <content:encoded>{{ post.content | devto_html: site_url | xml_escape }}</content:encoded>
     </item>
 {%- endfor %}

data/lib/jekyll/devto/html.rb

@@ -13,12 +13,16 @@ module Jekyll
     #   up inside the code.
     # - Root-relative links and images point nowhere once the post lives on
     #   dev.to.
+    #
+    # The code language cannot travel as a class, so each block carries it as
+    # data-lang, which CleanHtml keeps. ReverseMarkdown ignores it; the
+    # publisher reads it from the feed and writes it into the draft's fences.
     module HTML
       # Kramdown block options such as {: .nolineno } or {: file="..." } add
       # classes and attributes to the wrapper, so the class is matched anywhere
       # in the tag.
       ROUGE_BLOCK = %r{
-        <div\b[^>]*\bclass="[^"]*\bhighlighter-rouge\b[^"]*"[^>]*>\s*
+        <div\b(?<attrs>[^>]*\bclass="[^"]*\bhighlighter-rouge\b[^"]*"[^>]*)>\s*
         <div\ class="highlight">\s*<pre\ class="highlight"><code>
         (?<body>.*?)
         </code></pre>\s*</div>\s*</div>
@@ -26,7 +30,7 @@ module Jekyll
 
       # What the {% highlight %} Liquid tag renders.
       HIGHLIGHT_TAG = %r{
-        <figure\ class="highlight"><pre><code\b[^>]*>
+        <figure\ class="highlight"><pre><code\b(?<attrs>[^>]*)>
         (?<body>.*?)
         </code></pre></figure>
       }mx
@@ -40,31 +44,103 @@ module Jekyll
       TAG = /<[a-zA-Z][^>]*>/
       ROOT_RELATIVE = %r{\b(src|href)="/(?!/)}
 
+      # Kramdown's name for a fence with no language.
+      NO_LANGUAGE = %w[plaintext text].freeze
+
       module_function
 
       def convert(html, base_url)
         html.to_s
-          .gsub(ROUGE_BLOCK) { plain_code(Regexp.last_match[:body]) }
-          .gsub(HIGHLIGHT_TAG) { plain_code(Regexp.last_match[:body]) }
+          .gsub(ROUGE_BLOCK) { plain_code(Regexp.last_match[:body], rouge_language(Regexp.last_match[:attrs])) }
+          .gsub(HIGHLIGHT_TAG) { plain_code(Regexp.last_match[:body], Regexp.last_match[:attrs][/\bdata-lang="([^"]+)"/, 1]) }
           .gsub(TAG) { |tag| tag.gsub(ROOT_RELATIVE, %(\\1="#{base_url.to_s.chomp('/')}/)) }
       end
 
-      # The language is not kept: dev.to strips every class before converting,
-      # so it would never arrive.
-      def plain_code(body)
+      # Forem converts the HTML to Markdown only when block tags outnumber blank
+      # lines (Feeds::AssembleArticleMarkdown#html_content?); otherwise it stores
+      # the raw HTML, and none of the conversion (fences, languages) happens.
+      # Blank lines between tags are only formatting, and a newline inside code
+      # written as &#10; is the same character once parsed, so the post reads
+      # the same while the count of blank lines drops to zero.
+      def without_blank_lines(html)
+        html.split(%r{(<pre\b[^>]*>.*?</pre>)}m).map do |part|
+          part.start_with?('<pre') ? part.gsub("\n", '&#10;') : part.gsub(/\n\s*\n/, "\n")
+        end.join
+      end
+
+      # Kramdown writes the fence's language as a language-* class, and the
+      # language can hold any non-space character (c#, shell.session). It is
+      # read from the class attribute only, so another attribute such as
+      # file="docs/language-notes.md" cannot pass for it.
+      def rouge_language(attrs)
+        attrs[/\bclass="([^"]*)"/, 1].to_s[/(?:\A|\s)language-(\S+)/, 1]
+      end
+
+      def plain_code(body, language)
         body = Regexp.last_match[:code] if body =~ GUTTER
+        attribute = language && !NO_LANGUAGE.include?(language) ? %( data-lang="#{language}") : ''
+
+        "<pre#{attribute}><code>#{body.gsub(/<[^>]+>/, '')}</code></pre>"
+      end
+
+      # A post image as an absolute URL. Takes a path, a URL, or Chirpy's
+      # { "path" => ... } hash; nil when there is nothing to point at.
+      def absolute_url(value, base_url)
+        path = value.is_a?(Hash) ? value['path'] : value
+        return if path.to_s.empty?
+        return path if path.match?(%r{\Ahttps?://})
+        return "#{base_url.to_s[/\A[a-z][a-z0-9+.-]*:/i] || 'https:'}#{path}" if path.start_with?('//')
+
+        "#{base_url.to_s.chomp('/')}/#{path.sub(%r{\A/}, '')}"
+      end
+
+      CODE_BLOCK = %r{<pre\b(?<attrs>[^>]*)><code\b[^>]*>(?<code>.*?)</code></pre>}m
+
+      # Every code block in a converted body, in order, as [language, first
+      # line of code] (language is nil when the block has none). The first line
+      # is what identifies the block in the dev.to draft, whose fences do not
+      # always line up one to one with the blocks.
+      def code_blocks(html)
+        html.to_s.scan(CODE_BLOCK).map do |attrs, code|
+          [attrs[/\bdata-lang="([^"]+)"/, 1], first_line(unescape(code))]
+        end
+      end
+
+      # Whitespace is collapsed for the comparison: some Markdown converters
+      # squeeze runs of spaces inside code.
+      def first_line(code)
+        code.to_s.each_line.map { |line| line.split.join(' ') }.find { |line| !line.empty? }.to_s
+      end
 
-        "<pre><code>#{body.gsub(/<[^>]+>/, '')}</code></pre>"
+      # The entities this HTML can carry inside code; enough to compare it with
+      # the Markdown dev.to stores. &amp; goes last so "&amp;lt;" stays "&lt;".
+      def unescape(text)
+        text.gsub(/&#(\d+);/) { Regexp.last_match(1).to_i.chr(Encoding::UTF_8) }
+            .gsub('&lt;', '<').gsub('&gt;', '>').gsub('&quot;', '"').gsub('&#39;', "'").gsub('&amp;', '&')
       end
     end
 
     # Liquid filter for the feed template.
     module Filters
+      # devto_tags as a list, whether the front matter wrote a YAML list or a
+      # string ("ruby, rails" or "ruby rails", as Jekyll accepts for tags), so
+      # the import and the publisher see the same tags. nil when there are none.
+      def devto_list(value)
+        list = value.is_a?(Array) ? value.map(&:to_s) : value.to_s.split(/[,\s]+/)
+        list = list.map(&:strip).reject(&:empty?)
+        list unless list.empty?
+      end
+
+      def devto_url(value, base_url)
+        HTML.absolute_url(value, base_url).to_s
+      end
+
       def devto_html(html, base_url)
-        HTML.convert(html, base_url)
+        HTML.without_blank_lines(HTML.convert(html, base_url))
       end
     end
   end
 end
 
-Liquid::Template.register_filter(Jekyll::Devto::Filters)
+# The CLI loads this file without Jekyll, only for HTML.code_blocks.
+Liquid::Template.register_filter(Jekyll::Devto::Filters) if defined?(Liquid::Template)

data/lib/jekyll/devto/publisher.rb

@@ -4,6 +4,7 @@ require 'net/http'
 require 'rexml/document'
 require 'time'
 require_relative 'client'
+require_relative 'html'
 
 module Jekyll
   module Devto
@@ -17,7 +18,7 @@ module Jekyll
     class Publisher
       MAX_REDIRECTS = 5
 
-      Post = Struct.new(:title, :link, :date, keyword_init: true)
+      Post = Struct.new(:title, :link, :date, :code_blocks, :cover, :tags, :series, keyword_init: true)
 
       def initialize(feed:, client:, days: 7, publish: false, now: Time.now, out: $stdout, err: $stderr)
         @feed = feed
@@ -51,7 +52,7 @@ module Jekyll
 
           # One rejected post must not stop the rest, or every retry would stop at it.
           begin
-            result = @client.update(draft['id'], published: true, body_markdown: self.class.published_body(draft['body_markdown']))
+            result = @client.update(draft['id'], published: true, body_markdown: self.class.prepared_body(draft['body_markdown'], post, cover: new_cover(draft, post)))
             sent[draft['id']] = post
             @out.puts "  sent    #{post.title.inspect} -> #{result['url']}"
           rescue StandardError => e
@@ -76,17 +77,102 @@ module Jekyll
         end
       end
 
+      # The draft body to send: published, with each code fence given the
+      # language its block had on the site.
+      def self.prepared_body(markdown, post, cover: post.cover)
+        body = published_body(markdown)
+        body = with_front_matter(body, 'cover_image', cover) if cover
+        tags = devto_tags(post.tags.to_a)
+        body = with_front_matter(body, 'tags', tags, replace: true) unless tags.empty?
+        body = with_front_matter(body, 'series', yaml_string(post.series)) if post.series
+        with_code_languages(body, post.code_blocks.to_a)
+      end
+
+      # Adds `key: value` to the draft's front matter, which dev.to reads on
+      # every save (Article#evaluate_front_matter: cover_image, tags, series).
+      # A key the draft already has is kept, since it was set on dev.to on
+      # purpose, unless `replace:` says the site's value wins (devto_tags,
+      # which the author chose for dev.to explicitly).
+      def self.with_front_matter(markdown, key, value, replace: false)
+        # The key line plus any continuation lines (an indented or "- " list), so
+        # a replaced block list does not leave its items behind.
+        line = /^#{Regexp.escape(key)}:[^\r\n]*(?:\r?\n(?:[ \t]|-(?=[ \t\r\n]))[^\r\n]*)*/
+        markdown.to_s.sub(/\A---(\r?\n).*?^---[ \t]*\r?$/m) do |front_matter|
+          newline = Regexp.last_match(1)
+          if front_matter.match?(line)
+            next replace ? front_matter.sub(line) { "#{key}: #{value}" } : front_matter
+          end
+
+          front_matter.sub(/^---[ \t]*\r?\z/) { |closing| "#{key}: #{value}#{newline}#{closing}" }
+        end
+      end
+
+      # The cleanup dev.to's import applies to tags (Feeds::AssembleArticleMarkdown
+      # #get_tags): at most four, spaces and anything but letters and digits
+      # removed, 20 characters each. Lowercased as dev.to stores them
+      # (ActsAsTaggableOn.force_lowercase), so the dry run shows the real tags.
+      def self.devto_tags(tags)
+        tags.first(4).map { |tag| tag.delete(' ').gsub(/[^[:alnum:]]/, '')[0..19].downcase }.reject(&:empty?).join(',')
+      end
+
+      # A double-quoted YAML scalar, so a value such as "MDN: Spanish" stays a
+      # string instead of breaking the front matter. A JSON string is one.
+      def self.yaml_string(value)
+        JSON.generate(value.to_s)
+      end
+
+      # Writes each block's language into the draft's code fence. Blocks are
+      # matched by their first line of code, not by position: dev.to does not
+      # turn every block into a fence (one inside a list item can come out
+      # unfenced), and an edited draft may not line up either. Each block is
+      # used once, in order: a fence only matches blocks after the last one
+      # matched, so a block missing from the draft cannot lend its language to
+      # a later fence that starts the same way. A fence nothing matches, or
+      # one that already names a language, is left alone.
+      def self.with_code_languages(markdown, blocks)
+        lines = markdown.to_s.lines
+        cursor = 0
+        inside = false
+        lines.each_with_index do |line, index|
+          next unless line =~ /\A\s*```[^\s`]*\s*\z/
+
+          inside = !inside
+          next unless inside && line =~ /\A\s*```\s*\z/
+
+          first = HTML.first_line(lines[(index + 1)..].take_while { |l| l !~ /\A\s*```/ }.join)
+          match = (cursor...blocks.size).find { |i| blocks[i][1] == first }
+          next unless match
+
+          cursor = match + 1
+          language = blocks[match].first
+          lines[index] = line.sub('```', "```#{language}") if language
+        end
+        lines.join
+      end
+
       def due_posts
         REXML::Document.new(read_feed).get_elements('//item').filter_map do |item|
           date = Time.rfc2822(item.elements['pubDate'].text)
           next if date > @now || date < @now - (@days * 86_400)
 
-          Post.new(title: item.elements['title'].text.to_s.strip, link: item.elements['link'].text.to_s.strip, date: date)
+          Post.new(title: item.elements['title'].text.to_s.strip, link: item.elements['link'].text.to_s.strip, date: date,
+                   code_blocks: HTML.code_blocks(item.elements['content:encoded']&.text),
+                   cover: item.elements['devto:cover']&.text,
+                   tags: item.elements['devto:tags']&.text&.split(','),
+                   series: item.elements['devto:series']&.text)
         end
       end
 
       private
 
+      # A cover chosen in dev.to's editor lives in the article (main_image),
+      # not in the body's front matter, and a cover_image key in the front
+      # matter would replace it (Article#set_main_image). The API reports it
+      # as cover_image, so a draft that has one is left with it.
+      def new_cover(draft, post)
+        post.cover if draft['cover_image'].to_s.empty?
+      end
+
       # Follows redirects (http to https, apex to www), which Net::HTTP does not.
       def read_feed
         return File.read(@feed) unless @feed.match?(%r{\Ahttps?://})

data/lib/jekyll/devto/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module Devto
-    VERSION = '0.1.0'
+    VERSION = '0.3.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-devto
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Juan Vásquez
@@ -48,7 +48,7 @@ description: |
   Rouge line numbers, absolute links and images), and a command that
   publishes the imported drafts once their post is live on your site.
 email:
-- juan@ombulabs.com
+- hello@juanvasquez.dev
 executables:
 - jekyll-devto
 extensions: []