Merge pull request #148 from DannyBen/add/source-link

Add optional 'Page Source' link to all pages

.github/workflows/test.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
 
     strategy:
-      matrix: { ruby: ['2.7', '3.0', '3.1', '3.2', head] }
+      matrix: { ruby: ['3.0', '3.1', '3.2', head] }
 
     steps:
     - name: Checkout code

.rubocop.yml

@@ -8,7 +8,7 @@ inherit_gem:
     - rspec.yml
 
 AllCops:
-  TargetRubyVersion: 2.7
+  TargetRubyVersion: 3.0
   Exclude:
     - dev/**/*
     - debug.rb
@@ -33,4 +33,9 @@ RSpec/StubbedMock:
 # The `override_config` here is more complex
 Metrics/AbcSize:
   Exclude:
-    - lib/madness/commands/server.rb
+    - lib/madness/commands/server.rb
+
+# The main server route is long
+Metrics/BlockLength:
+  Exclude:
+    - lib/madness/server.rb

README.md

@@ -160,6 +160,20 @@ toc: ~
 # theme: _theme
 theme: ~
 
+# enable a link to the page's source at the bottom of each page by setting
+# a URL pattern here. Use '%{path}' anywhere in the string to get the
+# URI-encoded path of the page.
+# source_link: http://example.com/%{path}
+source_link: ~
+
+# if source_link is enabled, you can change the default link label
+# source_link_label: Edit Page
+source_link_label: Page Source
+
+# if source_link is enabled, you can change its position (top / bottom)
+# source_link_pos: top
+source_link_pos: bottom
+
 # open the server URL in the browser
 open: false
 

app/styles/_general.scss

@@ -34,3 +34,7 @@ mark {
 .quiet {
   color: var(--quiet-color);
 }
+
+.float-right {
+  float: right;
+}

app/styles/_manifest.scss

@@ -14,6 +14,7 @@
 @import "nav";
 @import "rouge";
 @import "scrollbar";
+@import "source_link";
 @import "search";
 @import "table";
 @import "typography";

app/styles/_source_link.scss

@@ -0,0 +1,8 @@
+.source-link {
+  margin-top: 13px;
+  float: right;
+
+  @include mobile {
+    display: none;
+  }
+}

app/views/document.slim

@@ -2,9 +2,16 @@
 == slim :_nav, locals: { nav: nav } if config.sidebar
 
 .main class=(config.sidebar ? 'with-sidebar' : 'without-sidebar')
+  - if source_link && source_link[:position] == 'top'
+    a.source-link href="#{source_link[:uri]}" = source_link[:label]
+
   == slim :_breadcrumbs, locals: { breadcrumbs: breadcrumbs }
   == content
 
   - if type != :file and config.auto_nav
     - if nav.links.any?
       == slim :_index_nav, locals: { nav: nav }
+
+  - if source_link && source_link[:position] == 'bottom'
+    hr
+    a href="#{source_link[:uri]}" = source_link[:label]

edge/op.conf

@@ -1,2 +1,10 @@
-build: docker build --build-arg=branch=${1:-master} --no-cache -t dannyben/madness:edge . && docker images |grep madness
+build: \
+  branch="$(git symbolic-ref --short HEAD)" && \
+  echo "Building for branch $branch" && \
+  docker build --build-arg=branch=${1:-$branch} --no-cache -t dannyben/madness:edge . && \
+  docker images |grep madness
+#? Build the docker edge image
+#? Usage: op build [BRANCH]
+
 push: docker push dannyben/madness:edge
+#? Push the edge image to Docker Hub

lib/madness/document.rb

@@ -18,6 +18,14 @@ def content
       @content ||= %i[empty missing].include?(type) ? "<h1>#{title}</h1>" : markdown.to_html
     end
 
+    def relative_file
+      file[%r{^#{docroot}/(.*)}, 1]
+    end
+
+    def href
+      relative_file.to_href
+    end
+
   private
 
     # Identify file, dir and type.

lib/madness/search.rb

@@ -39,7 +39,7 @@ def search(query)
     def index!
       results = {}
 
-      Dir["#{@path}/**/#{config.dir_glob}"].sort.each do |file|
+      Dir["#{@path}/**/#{config.dir_glob}"].each do |file|
         next if skip_index? file
 
         filename = file_url(file.sub("#{@path}/", '')).downcase

lib/madness/server.rb

@@ -48,13 +48,23 @@ class Server < ServerBase
 
       status 404 if doc.type == :missing
 
+      source_link = nil
+      if config.source_link && %i[file readme].include?(doc.type)
+        source_link = {
+          uri:      config.source_link % { path: doc.href },
+          label:    config.source_link_label,
+          position: config.source_link_pos,
+        }
+      end
+
       slim :document, locals: {
         content:     content,
         type:        doc.type,
         title:       doc.title,
         file:        doc.file,
         nav:         nav,
         breadcrumbs: breadcrumbs,
+        source_link: source_link,
       }
     end
   end

lib/madness/settings.rb

@@ -64,6 +64,9 @@ def defaults
         highlighter:       true,
         copy_code:         true,
         shortlinks:        false,
+        source_link:       nil,
+        source_link_label: 'Page Source',
+        source_link_pos:   'bottom',
         toc:               nil,
         theme:             nil,
         open:              false,

lib/madness/templates/madness.yml

@@ -46,6 +46,20 @@ toc: ~
 # theme: _theme
 theme: ~
 
+# enable a link to the page's source at the bottom of each page by setting
+# a URL pattern here. Use '%{path}' anywhere in the string to get the
+# URI-encoded path of the page.
+# source_link: http://example.com/%{path}
+source_link: ~
+
+# if source_link is enabled, you can change the default link label
+# source_link_label: Edit Page
+source_link_label: Page Source
+
+# if source_link is enabled, you can change its position (top / bottom)
+# source_link_pos: top
+source_link_pos: bottom
+
 # open the server URL in the browser
 open: false
 

madness.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |s|
   s.executables = ['madness']
   s.homepage    = 'https://github.com/DannyBen/madness'
   s.license     = 'MIT'
-  s.required_ruby_version = '>= 2.7'
+  s.required_ruby_version = '>= 3.0'
 
   s.add_runtime_dependency 'addressable', '~> 2.7'
   s.add_runtime_dependency 'colsole', '>= 0.8.1', '< 2'

spec/approvals/cli/config/show

@@ -9,6 +9,9 @@
          highlighter:  true
            copy_code:  true
           shortlinks:  ~
+         source_link:  ~
+   source_link_label:  Page Source
+     source_link_pos:  bottom
                  toc:  ~
                theme:  ~
                 open:  ~

spec/approvals/cli/config/show-non-default

@@ -9,6 +9,9 @@
          highlighter:  true
            copy_code:  true
           shortlinks:  ~
+         source_link:  ~
+   source_link_label:  Page Source
+     source_link_pos:  bottom
                  toc:  Table of Contents
                theme:  my_theme
                 open:  ~

spec/approvals/cli/theme/theme-ls

@@ -32,6 +32,7 @@
 - tmp/theme-test/styles/_rouge.scss
 - tmp/theme-test/styles/_scrollbar.scss
 - tmp/theme-test/styles/_search.scss
+- tmp/theme-test/styles/_source_link.scss
 - tmp/theme-test/styles/_table.scss
 - tmp/theme-test/styles/_typography.scss
 - tmp/theme-test/styles/_variables.scss

spec/madness/commands/theme_spec.rb

@@ -24,7 +24,7 @@
     it 'copies the default theme to a folder of our choice' do
       expect { subject.execute "theme full #{theme_dir}" }.to output_approval('cli/theme/full-create')
       expect(Dir).to exist theme_dir
-      expect(Dir["#{theme_dir}/**/*"].sort.to_yaml).to match_approval('cli/theme/theme-ls')
+      expect(Dir["#{theme_dir}/**/*"].to_yaml).to match_approval('cli/theme/theme-ls')
     end
 
     context 'when dir already exists' do

spec/madness/document_spec.rb

@@ -283,4 +283,20 @@
       end
     end
   end
+
+  describe '#relative_file' do
+    subject { described_class.new 'Folder/Subfolder/Subfile' }
+
+    it 'returns the path to the file without the docroot' do
+      expect(subject.relative_file).to eq 'Folder/Subfolder/Subfile.md'
+    end
+  end
+
+  describe '#href' do
+    subject { described_class.new 'Folder with Index' }
+
+    it 'returns a URI-encoded relative_file' do
+      expect(subject.href).to eq 'Folder%20with%20Index/index.md'
+    end
+  end
 end

spec/madness/server_spec.rb

@@ -161,6 +161,23 @@
       end
     end
 
+    context 'when source_link is enabled' do
+      before do
+        config.source_link = 'http://example.com/%{path}/edit'
+        config.source_link_label = 'Edit Me'
+      end
+
+      after do
+        config.source_link = nil
+        config.source_link_label = 'Page Source'
+      end
+
+      it 'adds a link to the source' do
+        get '/'
+        expect(last_response.body).to have_tag 'a', text: 'Edit Me', with: { href: 'http://example.com/README.md/edit' }
+      end
+    end
+
     # FIXME: This currently must be last - once basic auth is enabled, it is
     #        there for all eternity.
     context 'when basic authentication is enabled' do