diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 000000000..b6955042a
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,19 @@
+
+# Changelog
+
+## New in the version 3.1.0
+
+* [#227](https://github.com/geekq/workflow/pull/227) Allow event arguments to be taken into account when selecting the event
+* [#232](https://github.com/geekq/workflow/pull/232) Add ability to include partial workflow definitions for composability
+* [#241](https://github.com/geekq/workflow/pull/241) Example for defining workflow dynamically from JSON
+
+## New in the version 3.0.0
+
+* [#228](https://github.com/geekq/workflow/pull/228) Support for Ruby 3 keyword args, provided by @agirling
+* retire Ruby 2.6 since it has reached end of live; please use workflow 2.x, if you still depend on that Ruby version
+* [#229](https://github.com/geekq/workflow/pull/229) Switch from travis CI to GihHub actions for continuous integration
+
+## New in the versions 2.x
+
+* extract persistence adapters, Rails/ActiveRecord integration is now a separate gem
+  workflow-activerecord
diff --git a/README.adoc b/README.adoc
index 9d72f08f0..cfd7d547d 100644
--- a/README.adoc
+++ b/README.adoc
@@ -523,27 +523,6 @@ namespace :doc do
 end
 ```
 
-
-Changelog
----------
-
-=== New in the version 3.1.0
-
-* link:https://github.com/geekq/workflow/pull/227[#227] Allow event arguments to be taken into account when selecting the event
-* link:https://github.com/geekq/workflow/pull/232[#232] Add ability to include partial workflow definitions for composability
-* link:https://github.com/geekq/workflow/pull/241[#241] Example for defining workflow dynamically from JSON
-
-=== New in the version 3.0.0
-
-* link:https://github.com/geekq/workflow/pull/228[#228] Support for Ruby 3 keyword args, provided by @agirling
-* retire Ruby 2.6 since it has reached end of live; please use workflow 2.x, if you still depend on that Ruby version
-* link:https://github.com/geekq/workflow/pull/229[#229] Switch from travis CI to GihHub actions for continuous integration
-
-### New in the versions 2.x
-
-* extract persistence adapters, Rails/ActiveRecord integration is now a separate gem
-  workflow-activerecord
-
 Support, Participation
 ----------------------
 
diff --git a/workflow.gemspec b/workflow.gemspec
index 240a54678..747f726c4 100644
--- a/workflow.gemspec
+++ b/workflow.gemspec
@@ -18,6 +18,10 @@ Gem::Specification.new do |gem|
   gem.licenses      = ['MIT']
   gem.homepage      = "https://github.com/geekq/workflow"
 
+  gem.metadata["homepage_uri"] = gem.homepage
+  gem.metadata["source_code_uri"] = gem.homepage
+  gem.metadata["changelog_uri"] = "https://github.com/geekq/workflow/blob/develop/CHANGELOG.md"
+
   gem.files         = Dir['CHANGELOG.md', 'README.md', 'LICENSE', 'lib/**/*']
   gem.executables   = gem.files.grep(%r{^bin/}) { |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})