Output only main

build_docs.pl

@@ -333,11 +333,19 @@ sub check_links {
     check_kibana_links( $build_dir, $link_checker ) if exists $Conf->{repos}{kibana};
     # Comment out due to build errors
     # check_elasticsearch_links( $build_dir, $link_checker ) if exists $Conf->{repos}{elasticsearch};
-    if ( $link_checker->has_bad || $Opts->{warnlinkcheck}) {
+    if ( $Opts->{warnlinkcheck} || ($link_checker->has_bad && !$link_checker->has_warn)) {
+        #If --warnlinkcheck was specified or there are neither failing links nor warning links... don't die
         say $link_checker->report;
     }
     else {
-        die $link_checker->report;
+        if (!$link_checker->has_bad) {
+        # If --warnlinkcheck was not specified and there are failing links... die
+          die $link_checker->report;
+        }
+        else {
+        # If --warnlinkcheck was not specified and there are no failing links but there are warning links... don't die
+          say $link_checker->report;
+        }
     }
 }
 

integtest/spec/all_books_broken_link_detection_spec.rb

@@ -7,25 +7,33 @@
 # repositories or the book's configuration.
 RSpec.describe 'building all books' do
   KIBANA_LINKS_FILE = 'src/core/public/doc_links/doc_links_service.ts'
-  shared_context 'there is a broken link in the docs' do |text, check_links|
+  shared_context 'there is a broken link' do |text, check, fail|
     convert_before do |src, dest|
       repo = src.repo_with_index 'repo', text
       book = src.book 'Test'
       book.source repo, 'index.asciidoc'
       convert = dest.prepare_convert_all src.conf
-      convert.skip_link_check unless check_links
-      convert.convert(expect_failure: check_links)
+      convert.skip_link_check unless check
+      convert.convert(expect_failure: fail)
     end
   end
-  shared_context 'there is a broken absolute link in the docs' do |check_links|
-    include_context 'there is a broken link in the docs',
-                    'https://www.elastic.co/guide/foo', check_links
+  shared_context 'there is a broken absolute link' do |check, fail|
+    include_context 'there is a broken link',
+                    'https://www.elastic.co/guide/foo', check, fail
   end
-  shared_context 'there is a broken relative link in the docs' do |check_links|
-    include_context 'there is a broken link in the docs',
-                    'link:/guide/foo[]', check_links
+  shared_context 'there is a broken relative link' do |check, fail|
+    include_context 'there is a broken link',
+                    'link:/guide/foo[]', check, fail
   end
-  shared_context 'there is a kibana link' do |check_links, url, expect_failure|
+  shared_context 'there is a broken absolute link to master' do |check, fail|
+    include_context 'there is a broken link',
+                    'https://www.elastic.co/guide/master/foo', check, fail
+  end
+  shared_context 'there is a broken relative link to master' do |check, fail|
+    include_context 'there is a broken link',
+                    'link:/guide/master/foo[]', check, fail
+  end
+  shared_context 'there is a kibana link' do |check, url, fail|
     convert_before do |src, dest|
       # Kibana is special and we check links in it with a little magic
       kibana_repo = src.repo 'kibana'
@@ -57,33 +65,33 @@
       book.current_branch = 'main'
 
       convert = dest.prepare_convert_all src.conf
-      convert.skip_link_check unless check_links
-      convert.convert(expect_failure: expect_failure)
+      convert.skip_link_check unless check
+      convert.convert(expect_failure: fail)
     end
   end
-
-  shared_context 'there is a broken link in kibana' do |check_links|
-    # If we check links, we expect failure, and if we don't check links, we
-    # don't expect failure.
-    include_context 'there is a kibana link', check_links,
-                    '${ELASTIC_WEBSITE_URL}guide/foo', check_links
+  shared_context 'there is a broken link in kibana' do |check, fail|
+    include_context 'there is a kibana link', check,
+                    '${ELASTIC_WEBSITE_URL}guide/foo', fail
+  end
+  shared_context 'there is a broken link in kibana to master' do |check, fail|
+    include_context 'there is a kibana link', check,
+                    '${ELASTIC_WEBSITE_URL}guide/master/foo', fail
   end
-
   describe 'when broken link detection is disabled' do
-    describe 'when there is a broken absolute link in the docs' do
-      include_context 'there is a broken absolute link in the docs', false
+    describe 'when there is a broken absolute link' do
+      include_context 'there is a broken absolute link', false, false
       it 'logs that it skipped link checking' do
         expect(outputs[0]).to include('Skipped Checking links')
       end
     end
-    describe 'when there is a broken relative link in the docs' do
-      include_context 'there is a broken relative link in the docs', false
+    describe 'when there is a broken relative link' do
+      include_context 'there is a broken relative link', false, false
       it 'logs that it skipped link checking' do
         expect(outputs[0]).to include('Skipped Checking links')
       end
     end
     describe 'when there is a broken link in kibana' do
-      include_context 'there is a broken link in kibana', false
+      include_context 'there is a broken link in kibana', false, false
       it 'logs that it skipped link checking' do
         expect(outputs[0]).to include('Skipped Checking links')
       end
@@ -95,7 +103,7 @@
         expect(outputs[-1]).to include('All cross-document links OK')
       end
     end
-    shared_examples 'there are broken links in the docs' do
+    shared_examples 'there are broken links' do
       it 'logs there are bad cross document links' do
         expect(outputs[-1]).to include('Bad cross-document links:')
       end
@@ -106,6 +114,17 @@
         LOG
       end
     end
+    shared_examples 'there are broken links to master' do
+      it 'logs there are master links' do
+        expect(outputs[-1]).to include('Bad master links')
+      end
+      it 'logs the bad link to master' do
+        expect(outputs[-1]).to include(indent(<<~LOG.strip, '  '))
+          /tmp/docsbuild/target_repo/html/test/current/chapter.html contains broken links to:
+           - master/foo
+        LOG
+      end
+    end
     shared_examples 'there are broken links in kibana' do |url|
       it 'logs there are bad cross document links' do
         expect(outputs[-1]).to include('Bad cross-document links:')
@@ -117,6 +136,17 @@
         LOG
       end
     end
+    shared_examples 'there are broken links in kibana to master' do |url|
+      it 'logs there are bad cross document links' do
+        expect(outputs[-1]).to include('Bad master links:')
+      end
+      it 'logs the bad link' do
+        expect(outputs[-1]).to include(indent(<<~LOG.strip, '  '))
+          Kibana [master]: src/core/public/doc_links/doc_links_service.ts contains broken links to:
+           - #{url}
+        LOG
+      end
+    end
     describe 'when all of the links are intact' do
       convert_before do |src, dest|
         repo = src.repo_with_index(
@@ -129,45 +159,58 @@
       end
       include_examples 'all links are ok'
     end
-    describe 'when there is a broken absolute link in the docs' do
-      include_context 'there is a broken absolute link in the docs', true
-      include_examples 'there are broken links in the docs'
+    describe 'when there is a broken absolute link' do
+      include_context 'there is a broken absolute link', true, true
+      include_examples 'there are broken links'
+    end
+    describe 'when there is a broken relative link' do
+      include_context 'there is a broken relative link', true, true
+      include_examples 'there are broken links'
     end
-    describe 'when there is a broken relative link in the docs' do
-      include_context 'there is a broken relative link in the docs', true
-      include_examples 'there are broken links in the docs'
+    describe 'when there is a broken absolute link to master' do
+      include_context 'there is a broken absolute link to master', true, false
+      include_examples 'there are broken links to master'
+    end
+    describe 'when there is a broken relative link to master' do
+      include_context 'there is a broken relative link to master', true, false
+      include_examples 'there are broken links to master'
     end
     describe 'when there is a broken link in kibana' do
-      include_context 'there is a broken link in kibana', true
+      include_context 'there is a broken link in kibana', true, true
       include_examples 'there are broken links in kibana', 'foo'
     end
+    describe 'when there is a broken link in kibana to master' do
+      include_context 'there is a broken link in kibana to master', true, false
+      include_examples 'there are broken links in kibana to master',
+                       'master/foo'
+    end
     describe 'when a link in kibana goes to the website outside the guide' do
       include_context 'there is a kibana link', true,
                       '${ELASTIC_WEBSITE_URL}not-part-of-the-guide', false
       include_examples 'all links are ok'
     end
     describe 'when there is a broken Elasticsearch Guide link in Kibana' do
       include_context 'there is a kibana link', true,
-                      '${ELASTICSEARCH_DOCS}missing-page.html', true
-      include_examples 'there are broken links in kibana',
+                      '${ELASTICSEARCH_DOCS}missing-page.html', false
+      include_examples 'there are broken links in kibana to master',
                        'en/elasticsearch/reference/master/missing-page.html'
     end
     describe 'when there is a broken Kibana guide link' do
       include_context 'there is a kibana link', true,
-                      '${KIBANA_DOCS}not-a-kibana-page.html', true
-      include_examples 'there are broken links in kibana',
+                      '${KIBANA_DOCS}not-a-kibana-page.html', false
+      include_examples 'there are broken links in kibana to master',
                        'en/kibana/master/not-a-kibana-page.html'
     end
     describe 'when there is a broken ES Plugin link' do
       include_context 'there is a kibana link', true,
-                      '${PLUGIN_DOCS}not-valid-plugin.html', true
-      include_examples 'there are broken links in kibana',
+                      '${PLUGIN_DOCS}not-valid-plugin.html', false
+      include_examples 'there are broken links in kibana to master',
                        'en/elasticsearch/plugins/master/not-valid-plugin.html'
     end
     describe 'when there is a broken Fleet link' do
       include_context 'there is a kibana link', true,
-                      '${FLEET_DOCS}not-a-fleet-page.html', true
-      include_examples 'there are broken links in kibana',
+                      '${FLEET_DOCS}not-a-fleet-page.html', false
+      include_examples 'there are broken links in kibana to master',
                        'en/fleet/master/not-a-fleet-page.html'
     end
     describe 'when there is a broken APM link' do
@@ -178,38 +221,38 @@
     end
     describe 'when there is a broken Stack link' do
       include_context 'there is a kibana link', true,
-                      '${STACK_DOCS}not-a-stack-page.html', true
-      include_examples 'there are broken links in kibana',
+                      '${STACK_DOCS}not-a-stack-page.html', false
+      include_examples 'there are broken links in kibana to master',
                        'en/elastic-stack/master/not-a-stack-page.html'
     end
     describe 'when there is a broken Security link' do
       include_context 'there is a kibana link', true,
-                      '${SECURITY_SOLUTION_DOCS}not-a-security-page.html', true
-      include_examples 'there are broken links in kibana',
+                      '${SECURITY_SOLUTION_DOCS}not-a-security-page.html', false
+      include_examples 'there are broken links in kibana to master',
                        'en/security/master/not-a-security-page.html'
     end
     describe 'when there is a broken Stack Getting Started link' do
       include_context 'there is a kibana link', true,
-                      '${STACK_GETTING_STARTED}not-a-page.html', true
-      include_examples 'there are broken links in kibana',
+                      '${STACK_GETTING_STARTED}not-a-page.html', false
+      include_examples 'there are broken links in kibana to master',
                        'en/elastic-stack-get-started/master/not-a-page.html'
     end
     describe 'when there is a broken App Search link' do
       include_context 'there is a kibana link', true,
-                      '${APP_SEARCH_DOCS}not-a-search-page.html', true
-      include_examples 'there are broken links in kibana',
+                      '${APP_SEARCH_DOCS}not-a-search-page.html', false
+      include_examples 'there are broken links in kibana to master',
                        'en/app-search/master/not-a-search-page.html'
     end
     describe 'when there is a broken Enterprise Search link' do
       include_context 'there is a kibana link', true,
-                      '${ENTERPRISE_SEARCH_DOCS}not-a-search-page.html', true
-      include_examples 'there are broken links in kibana',
+                      '${ENTERPRISE_SEARCH_DOCS}not-a-search-page.html', false
+      include_examples 'there are broken links in kibana to master',
                        'en/enterprise-search/master/not-a-search-page.html'
     end
     describe 'when there is a broken Workplace Search link' do
       include_context 'there is a kibana link', true,
-                      '${WORKPLACE_SEARCH_DOCS}not-a-search-page.html', true
-      include_examples 'there are broken links in kibana',
+                      '${WORKPLACE_SEARCH_DOCS}not-a-search-page.html', false
+      include_examples 'there are broken links in kibana to master',
                        'en/workplace-search/master/not-a-search-page.html'
     end
     describe 'when using --keep_hash and --sub_dir together like a PR test' do

lib/ES/LinkCheck.pm

@@ -16,7 +16,7 @@ sub new {
 #===================================
     my $class = shift;
     my $root = shift or die "No root dir specified";
-    bless { root => $root, seen => {}, bad => {} }, $class;
+    bless { root => $root, seen => {}, bad => {}, warn => {} }, $class;
 }
 
 #===================================
@@ -38,7 +38,7 @@ sub check {
                 if $item->basename =~ /\.html$/;
         }
     );
-    return $self->has_bad;
+    return ($self->has_bad, $self->has_warn);
 
 }
 
@@ -63,7 +63,12 @@ sub check_source {
     while ( my ( $path, $fragment ) = $link_it->() ) {
         my $dest = $self->root->file($path);
         unless ( $self->_file_exists( $dest, $path ) ) {
-            $self->add_bad( $file_descr, $path );
+            if ($path =~ /master/) {
+              $self->add_warn( $file_descr, $path );
+            }
+            else {
+              $self->add_bad( $file_descr, $path );
+            }
             next;
         }
         next unless $fragment;
@@ -90,16 +95,25 @@ sub report {
 #===================================
     my $self = shift;
     my $bad  = $self->bad;
+    my $warn  = $self->warn;
     return "All cross-document links OK"
-        unless keys %$bad;
-
-    my @error = "Bad cross-document links:";
-    for my $file ( sort keys %$bad ) {
+        unless ( keys %$bad || keys %$warn );
+    if (keys %$bad) {
+      my @error = "Bad cross-document links:";
+      for my $file ( sort keys %$bad ) {
         push @error, "  $file contains broken links to:";
         push @error, map {"   - $_"} sort keys %{ $bad->{$file} };
+      }
+      die join "\n", @error, '';
+    }
+    if (keys %$warn) {
+      my @warning = "Bad master links:";
+      for my $file ( sort keys %$warn ) {
+        push @warning, "  $file contains broken links to:";
+        push @warning, map {"   - $_"} sort keys %{ $warn->{$file} };
+      }
+      return join "\n", @warning, '';
     }
-    return join "\n", @error, '';
-
 }
 
 #===================================
@@ -137,11 +151,20 @@ sub add_bad {
     $self->bad->{$file}{$id} = 1;
 }
 
+#===================================
+sub add_warn {
+#===================================
+    my ( $self, $file, $id ) = @_;
+    $self->warn->{$file}{$id} = 1;
+}
+
 #===================================
 sub root    { shift->{root} }
 sub seen    { shift->{seen} }
 sub bad     { shift->{bad} }
 sub has_bad { !keys %{ shift->bad } }
+sub warn     { shift->{warn} }
+sub has_warn { !keys %{ shift->warn } }
 #===================================
 
 1

shared/attributes.asciidoc

@@ -475,11 +475,11 @@ Legacy definitions
 :apm-get-started-ref:  https://www.elastic.co/guide/en/apm/get-started/{branch}
 :apm-server-ref:       https://www.elastic.co/guide/en/apm/server/{branch}
 :apm-server-ref-v:     https://www.elastic.co/guide/en/apm/server/{branch}
-:apm-server-ref-m:     https://www.elastic.co/guide/en/apm/server/master
+:apm-server-ref-m:     https://www.elastic.co/guide/en/apm/server/main
 :apm-server-ref-62:    https://www.elastic.co/guide/en/apm/server/6.2
 :apm-server-ref-64:    https://www.elastic.co/guide/en/apm/server/6.4
 :apm-server-ref-70:    https://www.elastic.co/guide/en/apm/server/7.0
 :apm-overview-ref-v:   https://www.elastic.co/guide/en/apm/get-started/{branch}
 :apm-overview-ref-70:  https://www.elastic.co/guide/en/apm/get-started/7.0
-:apm-overview-ref-m:   https://www.elastic.co/guide/en/apm/get-started/master
+:apm-overview-ref-m:   https://www.elastic.co/guide/en/apm/get-started/main
 :infra-guide:          https://www.elastic.co/guide/en/infrastructure/guide/{branch}