@trailstash/ultra/build-examples-docs.js

A web based tool for making MapLibre GL maps with data from sources such as Overpass, GeoJSON, GPX, KML, TCX, etc

import fs from "fs";
import path from "path";
import { parseSettings } from "./lib/settings.js";

function generateMarkdownForExample(config, file, queryContent, dir) {
  const { title, description } = config;
  const params = new URLSearchParams();
  params.set("query", queryContent);
  if (config.options?.center && config.options?.zoom !== undefined) {
    params.set(
      "m",
      `${config.options.zoom}/${config.options.center[1]}/${config.options.center[0]}`,
    );
  }
  let html = `
# ${title}

${description}

<iframe src="/#map&query=${encodeURIComponent(queryContent)}" width="100%" style="border:none; height:400px"></iframe>

\`\`\`
${queryContent}
\`\`\`
<br>
<a target="_blank" href="/#map&${params.toString()}">View Map on Ultra</a>
<br>
<a target="_blank" href="/#${params.toString()}">Edit Query on Ultra</a>`;
  if (dir.startsWith("MapLibre-Examples"))
    html += `<br>
<a target="_blank" href="https://maplibre.org/maplibre-gl-js/docs/examples/${file.replace(".ultra", "")}/">View MapLibre Example</a>
`;
  return html;
}

function generateMarkdownIndexFileOfAllExamples(examplesFolder, indexArray) {
  let indexMarkdown = "# Overview \n\n";
  const indexMdFile = path.join(examplesFolder, "index.md");
  if (fs.existsSync(indexMdFile)) {
    indexMarkdown = fs.readFileSync(indexMdFile, "utf-8");
  }
  for (const indexArrayItem of indexArray) {
    indexMarkdown += `
## [${indexArrayItem.title}](./${indexArrayItem.mdFileName})

[![${indexArrayItem.description}](../assets/${examplesFolder}/${indexArrayItem.mdFileName.replace(".md", ".png")})](./${indexArrayItem.mdFileName})


${indexArrayItem.description}
`;
  }
  return indexMarkdown;
}

/**
 * This takes the examples folder with all the html files and generates a markdown file for each of them.
 * It also create an index file with all the examples and their images.
 */
function generateExamplesFolder(examplesFolder) {
  const examplesDocsFolder = path.join("docs", examplesFolder);
  if (fs.existsSync(examplesDocsFolder)) {
    fs.rmSync(examplesDocsFolder, { recursive: true, force: true });
  }
  fs.mkdirSync(examplesDocsFolder);
  const files = fs
    .readdirSync(examplesFolder)
    .filter((f) => f.endsWith(".ultra"));
  const indexArray = [];
  for (const file of files) {
    const queryFile = path.join(examplesFolder, file);
    const queryContent = fs.readFileSync(queryFile, "utf-8");
    const config = parseSettings(queryContent);
    // fs.writeFileSync(path.join(examplesDocsFolder, file), queryContent);
    const mdFileName = file.replace(".ultra", ".md");
    indexArray.push({
      title: config.title,
      mdFileName,
      description: config.description,
      queryContent,
    });
    const exampleMarkdown = generateMarkdownForExample(
      config,
      file,
      queryContent,
      examplesFolder,
    );
    fs.writeFileSync(
      path.join(examplesDocsFolder, mdFileName),
      exampleMarkdown,
    );
  }

  const indexMarkdown = generateMarkdownIndexFileOfAllExamples(
    examplesFolder,
    indexArray,
  );
  fs.writeFileSync(path.join(examplesDocsFolder, "index.md"), indexMarkdown);
}

// !!Main flow start here!!
generateExamplesFolder(process.argv["2"] || "Examples");
console.log(
  "Docs generation completed, to see it in action run\n npm run start:docs",
);