Merge pull request #3523 from ClickHouse/Blargian-patch-2

Update style-guide

Author: gingerwizard

contribute/style-guide.md

@@ -206,7 +206,7 @@ export function Anchor(props) {
 ```
 - Replace `<span id="some-id"></span>` with `Anchor id="some-id"/>`
 
-### Dangling pages
+### Floating pages
 
 In order to prevent pages from becoming 'floating' or 'orphaned' it is
 necessary that you add a newly created page to `sidebars.js`. We have a [custom
@@ -215,3 +215,28 @@ docusaurus plugin](plugins/checkFloatingPages.js) to catch dangling pages.
 If there is some specific reason that you need to bypass this check, you can
 add an exception to `floating-pages-exceptions.txt` in the plugins directory.
 
+When adding a new page from the ClickHouse/ClickHouse repo this check will fail
+unless the file is in a folder which [`sidebars.js`](https://github.com/ClickHouse/clickhouse-docs/blob/main/sidebars.js)
+uses with `type: autogenerated` to generate the navigation items from the markdown
+files in the folder.
+
+If you've added a new page on ClickHouse/ClickHouse and this check is failing.
+
+For example:
+
+```text
+✅ All markdown files passed frontmatter validation.
+Loaded 3 exceptions from /opt/clickhouse-docs/plugins/floating-pages-exceptions.txt
+Skipping excepted page: index
+Skipping excepted page: integrations/language-clients/java/client-v1
+Skipping excepted page: integrations/language-clients/java/jdbc-v1
+�[31m1 floating pages found:�[0m
+  - /opt/clickhouse-docs/docs/operations/query-condition-cache.md
+```
+
+You will need to open a PR on docs repo to add this page to [`floating-pages-exceptions.txt`](https://github.com/ClickHouse/clickhouse-docs/blob/main/plugins/floating-pages-exceptions.txt). Once it is merged
+you can then rerun the docs check on the ClickHouse/ClickHouse repo which 
+should pass. Finally open another PR on the docs repo again to remove the 
+file from the exception list and add it to `sidebars.js` in the appropriate
+sidebar.
+

plugins/checkFloatingPages.js

@@ -94,13 +94,13 @@ async function checkFloatingPages(context, options = {}) {
                 if (options && options.failBuild) {
                     console.error('\x1b[31m%s\x1b[0m', `${floatingPages.length} floating pages found:`);
                     floatingPages.forEach(page => console.error(`  - ${page}`));
-                    throw new Error('🚨 Floating pages found. See above for details.');
+                    throw new Error('Error: Found "floating" pages without sidebars. For further details see: https://github.com/ClickHouse/clickhouse-docs/blob/main/contribute/style-guide.md/');
                 } else {
-                    console.log('⚠️', 'Found floating pages:');
+                    console.log('Warning:', 'Found floating pages:');
                     floatingPages.forEach(page => console.log(`  - ${page}`));
                 }
             } else {
-                console.log('✅', 'No floating pages found.');
+                console.log('Passed:', 'No floating pages found.');
             }
         }
     }

plugins/frontmatter-validation/frontmatterValidatorPlugin.js

@@ -44,7 +44,7 @@ function frontmatterValidatorPlugin(context, options) {
                     console.log('See frontmatter-validation-errors.log (when running locally)')
 
                     // Fail the build by throwing an error
-                    throw new Error('🚨Frontmatter validation failed. See frontmatter-validation-errors.log for details.');
+                    throw new Error('🚨Frontmatter validation failed. For more details see https://github.com/ClickHouse/clickhouse-docs/blob/main/contribute/style-guide.md');
                 } else {
                     console.log(`⚠️ Warning: Found ${filesWithIssues.length} files containing problems with frontmatter`)
                 }