build: transform guide markdown files with bazel (#14103)

* build: transform guide markdown files with bazel

* Initial implementation of a rule that can transform markdown files to the equivalent HTML output. This is the foundation for packaging the guides into the `//src/material-examples` package (see: #13454)

* Address feedback

Author: devversion

.circleci/config.yml

@@ -88,7 +88,6 @@ jobs:
       - *restore_cache
       - *copy_bazel_config
 
-      # TODO(jelbourn): Update this command to run all tests if the Bazel issues have been fixed.
       - run: bazel build src/...
       - run: bazel test src/... tools/public_api_guard/...
 

guides/BUILD.bazel

@@ -0,0 +1,8 @@
+package(default_visibility=["//visibility:public"])
+
+load("//tools/markdown-to-html:index.bzl", "markdown_to_html")
+
+markdown_to_html(
+  name = "guides",
+  srcs = glob(["**/*.md"]),
+)

package.json

@@ -115,6 +115,7 @@
     "karma-sauce-launcher": "^1.2.0",
     "karma-sourcemap-loader": "^0.3.7",
     "magic-string": "^0.22.4",
+    "marked": "^0.5.1",
     "minimatch": "^3.0.4",
     "minimist": "^1.2.0",
     "mock-fs": "^4.7.0",

tools/markdown-to-html/BUILD.bazel

@@ -0,0 +1,24 @@
+package(default_visibility = ["//visibility:public"])
+
+load("@build_bazel_rules_nodejs//:defs.bzl", "nodejs_binary")
+load("//tools:defaults.bzl", "ts_library")
+
+ts_library(
+  name = "transform-markdown",
+  srcs = [":transform-markdown.ts"],
+  deps = ["@matdeps//@types/node"],
+  tsconfig = ":tsconfig.json",
+)
+
+nodejs_binary(
+  name = "markdown-to-html",
+  entry_point = "angular_material/tools/markdown-to-html/transform-markdown.js",
+  data = [
+    "@matdeps//highlight.js",
+    "@matdeps//marked",
+    "@matdeps//source-map-support",
+    ":transform-markdown",
+  ],
+)
+
+

tools/markdown-to-html/index.bzl

@@ -0,0 +1,56 @@
+"""
+  Implementation of the "markdown_to_html" rule. The implementation runs the transform
+  executable in order to create the outputs for the specified source files.
+"""
+def _markdown_to_html(ctx):
+  input_files = ctx.files.srcs;
+  args = ctx.actions.args()
+  expected_outputs = [];
+
+  # Add the bazel bin directory to the command arguments. The script needs to know about
+  # the output directory because the input files are not in the same location as the bazel
+  # bin directory.
+  args.add(ctx.bin_dir.path)
+
+  for input_file in input_files:
+    # Remove the extension from the input file path. Note that we should not use `.replace`
+    # here because the extension can be also in upper case.
+    basename = input_file.basename[:-len(".md")]
+
+    # For each input file "xxx.md", we want to write an output file "xxx.html"
+    expected_outputs += [ctx.actions.declare_file("%s.html" % basename)]
+
+    # Add the input file to the command line arguments that will be passed to the
+    # transform-markdown executable.
+    args.add(input_file.path)
+
+  # Run the transform markdown executable that transforms the specified source files.
+  # Note that we should specify the outputs here because Bazel can then throw an error
+  # if the script didn't generate the required outputs.
+  ctx.actions.run(
+    inputs = input_files,
+    executable = ctx.executable._transform_markdown,
+    outputs = expected_outputs,
+    arguments = [args],
+  )
+
+  return DefaultInfo(files = depset(expected_outputs))
+
+"""
+  Rule definition for the "markdown_to_html" rule that can accept arbritary source files
+  that will be transformed into HTML files. The outputs can be referenced through the
+  default output provider.
+"""
+markdown_to_html = rule(
+  implementation = _markdown_to_html,
+  attrs = {
+    "srcs": attr.label_list(allow_files = [".md"]),
+
+    # Executable for this rule that is responsible for converting the specified
+    # markdown files into HTML files.
+    "_transform_markdown": attr.label(
+      default = Label("//tools/markdown-to-html"),
+      executable = True,
+      cfg = "host"
+  )},
+)

tools/markdown-to-html/transform-markdown.ts

@@ -0,0 +1,40 @@
+/**
+ * Script that will be used by the markdown_to_html Bazel rule in order to transform
+ * multiple markdown files into the equivalent HTML output.
+ */
+
+import {readFileSync, writeFileSync} from 'fs';
+import {join} from 'path';
+
+// These types lack type definitions.
+const marked = require('marked');
+const highlightJs = require('highlight.js');
+
+// Regular expression that matches the markdown extension of a given path.
+const markdownExtension = /.md$/;
+
+// Setup the default options for converting markdown to HTML.
+marked.setOptions({
+  // Implement a highlight function that converts the code block into a highlighted
+  // HTML snippet that uses HighlightJS.
+  highlight: (code: string, language: string): string => {
+    if (language) {
+      return highlightJs.highlight(
+          language.toLowerCase() === 'ts' ? 'typescript' : language, code).value;
+    }
+    return code;
+  }
+});
+
+if (require.main === module) {
+  // The script expects the bazel-bin path as first argument. All remaining arguments will be
+  // considered as markdown input files that need to be transformed.
+  const [bazelBinPath, ...inputFiles] = process.argv.slice(2);
+
+  // Walk through each input file and write transformed markdown output to the specified
+  // Bazel bin directory.
+  inputFiles.forEach(inputPath => {
+    const outputPath = join(bazelBinPath, inputPath.replace(markdownExtension, '.html'));
+    writeFileSync(outputPath, marked(readFileSync(inputPath, 'utf8')));
+  });
+}

tools/markdown-to-html/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "lib": ["es2015"],
+    "module": "commonjs",
+    "target": "es5",
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "bazelOptions": {
+    "suppressTsconfigOverrideWarnings": true
+  }
+}

yarn.lock

@@ -7469,6 +7469,11 @@ marked@^0.3.2:
   resolved "https://registry.yarnpkg.com/marked/-/marked-0.3.19.tgz#5d47f709c4c9fc3c216b6d46127280f40b39d790"
   integrity sha512-ea2eGWOqNxPcXv8dyERdSr/6FmzvWwzjMxpfGB/sbMccXoct+xY+YukPD+QTUZwyvK7BZwcr4m21WBOW41pAkg==
 
+marked@^0.5.1:
+  version "0.5.1"
+  resolved "https://registry.yarnpkg.com/marked/-/marked-0.5.1.tgz#062f43b88b02ee80901e8e8d8e6a620ddb3aa752"
+  integrity sha512-iUkBZegCZou4AdwbKTwSW/lNDcz5OuRSl3qdcl31Ia0B2QPG0Jn+tKblh/9/eP9/6+4h27vpoh8wel/vQOV0vw==
+
 matchdep@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/matchdep/-/matchdep-2.0.0.tgz#c6f34834a0d8dbc3b37c27ee8bbcb27c7775582e"