Merge pull request #26260 from github/repo-sync

Repo sync

Author: docs-bot

.github/actions-scripts/rendered-content-link-checker.js

@@ -14,15 +14,15 @@ import contextualize from '../../middleware/context.js'
 import features from '../../middleware/contextualizers/features.js'
 import getRedirect from '../../lib/get-redirect.js'
 import warmServer from '../../lib/warm-server.js'
-import liquid from '../../lib/render-content/liquid.js'
+import { liquid } from '../../src/content-render/index.js'
 import { deprecated } from '../../lib/enterprise-server-releases.js'
 import excludedLinks from '../../lib/excluded-links.js'
 import { getEnvInputs, boolEnvVar } from './lib/get-env-inputs.js'
 import { debugTimeEnd, debugTimeStart } from './lib/debug-time-taken.js'
 import { uploadArtifact as uploadArtifactLib } from './lib/upload-artifact.js'
 import github from '../../script/helpers/github.js'
 import { getActionContext } from './lib/action-context.js'
-import { createMinimalProcessor } from '../../lib/render-content/create-processor.js'
+import { createMinimalProcessor } from '../../src/content-render/unified/processor.js'
 
 const STATIC_PREFIXES = {
   assets: path.resolve('assets'),

lib/get-mini-toc-items.js

@@ -1,7 +1,7 @@
 import cheerio from 'cheerio'
 import { range } from 'lodash-es'
 
-import renderContent from './render-content/index.js'
+import { renderContent } from '#src/content-render/index.js'
 
 // Keep maxHeadingLevel=2 for accessibility reasons, see docs-engineering#2701 for more info
 export default function getMiniTocItems(html, maxHeadingLevel = 2, headingScope = '') {

lib/page.js

@@ -9,7 +9,7 @@ import getTocItems from './get-toc-items.js'
 import pathUtils from './path-utils.js'
 import Permalink from './permalink.js'
 import languages from './languages.js'
-import renderContent from './render-content/index.js'
+import { renderContent } from '#src/content-render/index.js'
 import processLearningTracks from '#src/learning-track/lib/process-learning-tracks.js'
 import { productMap } from './all-products.js'
 import slash from 'slash'

lib/release-notes-utils.js

@@ -1,5 +1,5 @@
 import semver from 'semver'
-import renderContent from './render-content/index.js'
+import { renderContent } from '#src/content-render/index.js'
 
 /**
  * Create an array of release note objects and sort them by number.

lib/render-content/README.md

@@ -1,6 +1,6 @@
-import renderContent from './render-content/index.js'
+import { renderContent } from '#src/content-render/index.js'
 import Page from './page.js'
-import { TitleFromAutotitleError } from './render-content/plugins/rewrite-local-links.js'
+import { TitleFromAutotitleError } from '#src/content-render/unified/rewrite-local-links.js'
 
 class EmptyTitleError extends Error {}
 

lib/render-content/index.js

@@ -1,5 +1,5 @@
 import path from 'path'
-import liquid from '../../lib/render-content/liquid.js'
+import { liquid } from '#src/content-render/index.js'
 import findPageInSiteTree from '../../lib/find-page-in-site-tree.js'
 import removeFPTFromPath from '../../lib/remove-fpt-from-path.js'
 import { executeWithFallback } from '../../lib/render-with-fallback.js'

lib/render-content/liquid.js

@@ -1,5 +1,5 @@
 import { getDataByLanguage } from '../../lib/get-data.js'
-import liquid from '../../lib/render-content/liquid.js'
+import { liquid } from '#src/content-render/index.js'
 import { executeWithFallback } from '../../lib/render-with-fallback.js'
 import { correctTranslatedContentStrings } from '../../lib/correct-translation-content.js'
 

lib/render-content/renderContent.js

@@ -6,7 +6,7 @@ import { execSync } from 'child_process'
 import { program } from 'commander'
 import fpt from '../../lib/non-enterprise-default-version.js'
 import { allVersionKeys } from '../../lib/all-versions.js'
-import { liquid } from '../../lib/render-content/index.js'
+import { liquid } from '#src/content-render/index.js'
 import contextualize from '../../middleware/context.js'
 
 const layoutFilename = path.posix.join(process.cwd(), 'script/dev-toc/layout.html')

lib/render-with-fallback.js

@@ -19,7 +19,7 @@ import walk from 'walk-sync'
 import slash from 'slash'
 import GithubSlugger from 'github-slugger'
 import { decode } from 'html-entities'
-import renderContent from '../lib/render-content/index.js'
+import { renderContent } from '#src/content-render/index.js'
 
 const slugger = new GithubSlugger()
 

middleware/contextualizers/current-product-tree.js

@@ -1,5 +1,5 @@
 import { addError, forEachInlineChild } from 'markdownlint-rule-helpers'
-import renderContent from '../../../../lib/render-content/index.js'
+import { renderContent } from '#src/content-render/index.js'
 
 export const incorrectAltTextLength = {
   names: ['MD111', 'incorrect-alt-text-length'],

middleware/contextualizers/glossaries.js

@@ -7,7 +7,7 @@ import GithubSlugger from 'github-slugger'
 import { decode } from 'html-entities'
 
 import matter from '../../../lib/read-frontmatter.js'
-import renderContent from '../../../lib/render-content/index.js'
+import { renderContent } from '#src/content-render/index.js'
 import getApplicableVersions from '../../../lib/get-applicable-versions.js'
 import contextualize from '../../../middleware/context.js'
 import shortVersions from '../../../middleware/contextualizers/short-versions.js'

script/dev-toc/generate.js

@@ -16,10 +16,10 @@ import { jest } from '@jest/globals'
 
 import { frontmatter, deprecatedProperties } from '../../../lib/frontmatter.js'
 import languages from '../../../lib/languages.js'
-import { tags } from '../../../lib/liquid-tags/extended-markdown.js'
+import { tags } from '#src/content-render/liquid/extended-markdown.js'
 import releaseNotesSchema from '../lib/release-notes-schema.js'
 import learningTracksSchema from '../lib/learning-tracks-schema.js'
-import renderContent from '../../../lib/render-content/index.js'
+import { renderContent } from '#src/content-render/index.js'
 import getApplicableVersions from '../../../lib/get-applicable-versions.js'
 import { allVersions } from '../../../lib/all-versions.js'
 import { getDiffFiles } from '../lib/diff-files.js'

script/reconcile-category-dirs-with-ids.js

@@ -7,7 +7,7 @@ import semver from 'semver'
 import { allVersions, allVersionShortnames } from '../../../lib/all-versions.js'
 import { supported, next, nextNext, deprecated } from '../../../lib/enterprise-server-releases.js'
 import { getLiquidConditionals } from '../../../script/helpers/get-liquid-conditionals.js'
-import allowedVersionOperators from '../../../lib/liquid-tags/ifversion-supported-operators.js'
+import allowedVersionOperators from '#src/content-render/liquid/ifversion-supported-operators.js'
 import featureVersionsSchema from '../lib/feature-versions-schema.js'
 import walkFiles from '../../../script/helpers/walk-files.js'
 import { getDeepDataByLanguage } from '../../../lib/get-data.js'

src/content-linter/lib/linting-rules/image-alt-text-length.js

@@ -1,4 +1,55 @@
-# Liquid Tags
+# Render content
+
+In this directory is the main pipeline that converts our content from Liquid, Markdown and YAML into HTML. This directory _does not include React components_.
+
+## Usage
+
+```js
+const renderContent = require('.')
+
+const html = await renderContent(`
+# Beep
+{{ foo }}
+`, {
+  foo: 'bar'
+})
+```
+
+Creates:
+
+```html
+<h1 id="beep"><a href="#beep">Beep</a></h1>
+<p>bar</p>
+```
+
+## API
+
+### renderContent(markdown, context = {}, options = {})
+
+Render a string of `markdown` with optional `context`. Returns a `Promise`.
+
+Liquid will be looking for includes in `${process.cwd()}/includes`.
+
+Options:
+
+- `fileName`: File name for debugging purposes.
+- `textOnly`: Output text instead of html using [cheerio](https://ghub.io/cheerio).
+
+### .liquid
+
+The [Liquid](https://ghub.io/liquidjs) instance used internally.
+
+### Code block headers
+
+You can add a header to code blocks by adding the ` copy` annotation after the code fences, and a specified language:
+
+    ```js copy
+    const copyMe = true
+    ```
+
+The un-highlighted text is available as `button.js-btn-copy`'s `data-clipboard-text` attribute.
+
+## Liquid tags
 
 See also [contributing/liquid-helpers.md](../../contributing/liquid-helpers.md)
 
@@ -36,7 +87,7 @@ Each custom tag has the following:
 
 The class and the template should have corresponding names, like `lib/liquid-tags/my-tag.js` and `includes/liquid-tags/my-tag.html`
 
-You must also register the new tag in `lib/render-content/index.js` with a line like this:
+You must also register the new tag in `src/content-render/liquid/engine.js` with a line like this:
 
 ```
 renderContent.liquid.registerTag('my_tag', require('./liquid-tags/my-tag'))

src/content-linter/tests/category-pages.js

@@ -0,0 +1,22 @@
+import { renderLiquid } from './liquid/index.js'
+import { renderUnified } from './unified/index.js'
+import { engine } from './liquid/engine.js'
+
+// parse multiple times because some templates contain more templates. :]
+export async function renderContent(template = '', context = {}, options = {}) {
+  // If called with a falsy template, it can't ever become something
+  // when rendered. We can exit early to save some pointless work.
+  if (!template) return template
+  try {
+    template = await renderLiquid(template, context)
+    const html = await renderUnified(template, context, options)
+    return html
+  } catch (error) {
+    if (options.filename) {
+      console.error(`renderContent failed on file: ${options.filename}`)
+    }
+    throw error
+  }
+}
+
+export const liquid = engine