ol-stac 0.0.0

package/examples/webpack/example-builder.js

@@ -0,0 +1,410 @@
+import assert from 'assert';
+import frontMatter from 'front-matter';
+import fs from 'fs';
+import fse from 'fs-extra';
+import handlebars from 'handlebars';
+import path, {dirname} from 'path';
+import sources from 'webpack-sources';
+import {fileURLToPath} from 'url';
+import {marked} from 'marked';
+
+const RawSource = sources.RawSource;
+const baseDir = dirname(fileURLToPath(import.meta.url));
+
+const isCssRegEx = /\.css(\?.*)?$/;
+const isJsRegEx = /\.js(\?.*)?$/;
+const importRegEx = /\s?import .*? from '([^']+)'/g;
+const isTemplateJs = /\/(?:bootstrap(?:\.bundle)?)(?:\.min)?\.js(?:\?.*)?$/;
+const isTemplateCss =
+  /\/(?:bootstrap|fontawesome-free@[\d.]+\/css\/(?:fontawesome|brands|solid))(?:\.min)?\.css(?:\?.*)?$/;
+
+const exampleDirContents = fs
+  .readdirSync(path.join(baseDir, '..'))
+  .filter((name) => /^(?!index).*\.html$/.test(name))
+  .map((name) => name.replace(/\.html$/, ''));
+
+function getPackageInfo() {
+  return fse.readJSON(path.resolve(baseDir, '../../package.json'));
+}
+
+handlebars.registerHelper(
+  'md',
+  (str) =>
+    new handlebars.SafeString(marked(str, {headerIds: false, mangle: false}))
+);
+
+/**
+ * Used to doube-escape the title when stored as data-* attribute.
+ */
+handlebars.registerHelper('escape', (text) => {
+  return handlebars.Utils.escapeExpression(text);
+});
+
+handlebars.registerHelper('indent', (text, options) => {
+  if (!text) {
+    return text;
+  }
+  const count = options.hash.spaces || 2;
+  const spaces = new Array(count + 1).join(' ');
+  return text
+    .split('\n')
+    .map((line) => (line ? spaces + line : ''))
+    .join('\n');
+});
+
+/**
+ * Returns the object with the keys inserted in alphabetic order.
+ * When exporting with `JSON.stringify(obj)` the keys are sorted.
+ * @param {Object<string, *>} obj Any object
+ * @return {Object<string, *>} New object
+ */
+function sortObjectByKey(obj) {
+  return Object.keys(obj)
+    .sort() // sort twice to get predictable, case insensitive order
+    .sort((a, b) => a.localeCompare(b, 'en', {sensitivity: 'base'}))
+    .reduce((idx, tag) => {
+      idx[tag] = obj[tag];
+      return idx;
+    }, {});
+}
+
+/**
+ * Create an index of tags belonging to examples
+ * @param {Array<Object>} exampleData Array of example data objects.
+ * @return {Object} Word index.
+ */
+function createTagIndex(exampleData) {
+  const index = {};
+  exampleData.forEach((data, i) => {
+    data.tags.forEach((tag) => {
+      tag = tag.toLowerCase();
+      let tagIndex = index[tag];
+      if (!tagIndex) {
+        tagIndex = [];
+        index[tag] = tagIndex;
+      }
+      tagIndex.push(i);
+    });
+  });
+  return index;
+}
+
+/**
+ * Create an inverted index of keywords from examples.  Property names are
+ * lowercased words.  Property values are objects mapping example index to word
+ * count.
+ * @param {Array<Object>} exampleData Array of example data objects.
+ * @return {Object} Word index.
+ */
+function createWordIndex(exampleData) {
+  const index = {};
+  const keys = ['shortdesc', 'title', 'tags'];
+  exampleData.forEach((data, i) => {
+    keys.forEach((key) => {
+      let text = data[key] || '';
+      if (Array.isArray(text)) {
+        text = text.join(' ');
+      }
+      const words = text.toLowerCase().split(/\W+/);
+      words.forEach((word) => {
+        if (word) {
+          let counts = index[word];
+          if (!counts) {
+            counts = {};
+            index[word] = counts;
+          }
+          counts[i] = (counts[i] || 0) + 1;
+        }
+      });
+    });
+  });
+  return index;
+}
+
+/**
+ * Gets dependencies from the js source.
+ * @param {string} jsSource Source.
+ * @param {Object} pkg Package info.
+ * @return {Object<string, string>} dependencies
+ */
+function getDependencies(jsSource, pkg) {
+  const dependencies = {
+    ol: pkg.version,
+  };
+
+  let importMatch;
+  while ((importMatch = importRegEx.exec(jsSource))) {
+    const imp = importMatch[1];
+    if (!imp.startsWith('ol/') && imp != 'ol') {
+      const parts = imp.split('/');
+      const dep = imp.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+      if (dep in pkg.devDependencies) {
+        dependencies[dep] = pkg.devDependencies[dep];
+      } else if (dep in pkg.dependencies) {
+        dependencies[dep] = pkg.dependencies[dep];
+      }
+    }
+  }
+  return dependencies;
+}
+
+export default class ExampleBuilder {
+  /**
+   * A webpack plugin that builds the html files for our examples.
+   * @param {Object} config Plugin configuration.  Requires a `templates` property
+   * with the path to templates and a `common` property with the name of the
+   * common chunk.
+   */
+  constructor(config) {
+    this.name = 'ExampleBuilder';
+    this.templates = config.templates;
+    this.common = config.common;
+  }
+
+  /**
+   * Called by webpack.
+   * @param {Object} compiler The webpack compiler.
+   */
+  apply(compiler) {
+    compiler.hooks.compilation.tap(this.name, (compilation) => {
+      compilation.hooks.additionalAssets.tapPromise(this.name, async () => {
+        await this.addAssets(compilation.assets, compiler.context);
+      });
+    });
+  }
+
+  async addAssets(assets, dir) {
+    const jsAssetRE = /^[\w-]+\.js$/;
+    const names = [];
+    for (const filename in assets) {
+      if (!jsAssetRE.test(filename)) {
+        continue;
+      }
+
+      const name = filename.replace(/\.js$/, '');
+      if (!exampleDirContents.includes(name)) {
+        continue;
+      }
+
+      names.push(name);
+    }
+
+    if (names.length === 0) {
+      return;
+    }
+
+    const exampleData = await Promise.all(
+      names.map((name) => this.parseExample(dir, name))
+    );
+
+    const examples = exampleData.map((data) => ({
+      link: data.filename,
+      title: data.title,
+      shortdesc: data.shortdesc,
+      tags: data.tags,
+    }));
+
+    examples.sort((a, b) =>
+      a.title.localeCompare(b.title, 'en', {sensitivity: 'base'})
+    );
+    const tagIndex = createTagIndex(examples);
+    const info = {
+      examples: examples,
+      // Tags for main page... TODO: implement index tag links
+      // tagIndex: sortObjectByKey(tagIndex),
+      wordIndex: sortObjectByKey(createWordIndex(examples)),
+    };
+    exampleData.forEach((data) => {
+      data.tags = data.tags.map((tag) => {
+        const tagExamples = tagIndex[tag.toLowerCase()];
+        return {
+          tag: tag,
+          examples: tagExamples.map((exampleIdx) => {
+            const example = examples[exampleIdx];
+            return {
+              link: example.link,
+              title: example.title,
+              isCurrent: data.filename === example.link,
+            };
+          }),
+        };
+      });
+    });
+
+    const pkg = await getPackageInfo();
+    await Promise.all(
+      exampleData.map(async (data) => {
+        const newAssets = await this.render(data, pkg);
+        for (const file in newAssets) {
+          assets[file] = new RawSource(newAssets[file]);
+        }
+      })
+    );
+
+    const indexSource = `const info = ${JSON.stringify(info)};`;
+    assets['examples-info.js'] = new RawSource(indexSource);
+  }
+
+  async parseExample(dir, name) {
+    const htmlName = `${name}.html`;
+    const htmlPath = path.join(dir, htmlName);
+    const htmlSource = await fse.readFile(htmlPath, {encoding: 'utf8'});
+    const {attributes: data, body} = frontMatter(
+      this.ensureNewLineAtEnd(htmlSource)
+    );
+    assert(!!data.layout, `missing layout in ${htmlPath}`);
+    return Object.assign(data, {
+      contents: body,
+      filename: htmlName,
+      dir: dir,
+      name: name,
+      // process tags
+      tags: data.tags ? data.tags.replace(/[\s"]+/g, '').split(',') : [],
+    });
+  }
+
+  /**
+   * @param {string} source A string
+   * @return {string} Same string without a newline character at end
+   */
+  ensureNewLineAtEnd(source) {
+    if (source[source.length - 1] !== '\n') {
+      source += '\n';
+    }
+    return source;
+  }
+
+  /**
+   * @param {string} source Source code
+   * @return {string} Transformed source
+   */
+  transformJsSource(source) {
+    return (
+      source
+        // remove "../src/" prefix to have the same import syntax as the documentation
+        .replace(/'\.\.\/src\//g, "'")
+    );
+  }
+
+  /**
+   * @param {string} source Source file
+   * @param {Array<{key: string, value: string}>|undefined} cloak Replacement rules
+   * @return {string} The source with all keys replaced by value
+   */
+  cloakSource(source, cloak) {
+    if (cloak) {
+      for (const entry of cloak) {
+        source = source.replaceAll(entry.key, entry.value);
+      }
+    }
+    return source;
+  }
+
+  async render(data, pkg) {
+    const assets = {};
+    const readOptions = {encoding: 'utf8'};
+
+    // add in script tag
+    const jsName = `${data.name}.js`;
+    const jsPath = path.join(data.dir, jsName);
+    let jsSource = await fse.readFile(jsPath, {encoding: 'utf8'});
+    jsSource = this.transformJsSource(this.cloakSource(jsSource, data.cloak));
+    data.js = {
+      local: [],
+      remote: [],
+      source: jsSource,
+    };
+
+    let jsSources = jsSource;
+    if (data.sources) {
+      data.extraSources = await Promise.all(
+        data.sources.map(async (sourceConfig) => {
+          const fileName = sourceConfig.path;
+          const extraSourcePath = path.join(data.dir, fileName);
+          let source = await fse.readFile(extraSourcePath, readOptions);
+          let ext = fileName.match(/\.(\w+)$/)[1];
+          if (ext === 'mjs') {
+            ext = 'js';
+          }
+          if (ext === 'js') {
+            source = this.transformJsSource(source);
+            jsSources += '\n' + source;
+          }
+          source = this.cloakSource(source, data.cloak);
+          assets[fileName] = source;
+          return {
+            name: sourceConfig.as || fileName,
+            source: source,
+            type: ext,
+          };
+        })
+      );
+    }
+
+    data.olVersion = pkg.version;
+    data.pkgJson = JSON.stringify(
+      {
+        name: data.name,
+        dependencies: getDependencies(jsSources, pkg),
+        devDependencies: {
+          vite: '^3.2.3',
+        },
+        scripts: {
+          start: 'vite',
+          build: 'vite build',
+        },
+      },
+      null,
+      2
+    );
+
+    data.css = {
+      local: [],
+      remote: [],
+      source: undefined,
+    };
+
+    // add additional resources
+    if (data.resources) {
+      data.resources.forEach((resource) => {
+        const absoluteUrl = /^https?:\/\//.test(resource)
+          ? resource
+          : `https://m-mohr.github.io/ol-stac/en/v${pkg.version}/examples/${resource}`;
+        if (isJsRegEx.test(resource)) {
+          if (!isTemplateJs.test(resource)) {
+            data.js.local.push(resource);
+          }
+          data.js.remote.push(absoluteUrl);
+        } else if (isCssRegEx.test(resource)) {
+          if (!isTemplateCss.test(resource)) {
+            data.css.local.push(resource);
+          }
+          data.css.remote.push(absoluteUrl);
+        } else {
+          throw new Error(
+            `Invalid resource: '${resource}' is not .js or .css: ${data.filename}`
+          );
+        }
+      });
+    }
+
+    data.js.local.push(`${this.common}.js`, jsName);
+
+    // check for example css
+    const cssName = `${data.name}.css`;
+    const cssPath = path.join(data.dir, cssName);
+    try {
+      assets[cssName] = await fse.readFile(cssPath, readOptions);
+      data.css.local.push(cssName);
+      data.css.source = this.ensureNewLineAtEnd(assets[cssName]);
+    } catch (err) {
+      // pass, no css for this example
+    }
+
+    const templatePath = path.join(this.templates, data.layout);
+    const templateSource = await fse.readFile(templatePath, readOptions);
+
+    assets[data.filename] = handlebars.compile(templateSource)(data);
+    return assets;
+  }
+}

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "ol-stac",
+  "version": "0.0.0",
+  "description": "An \"automagical\" STAC LayerGroup for OpenLayers",
+  "homepage": "https://mohr.ws",
+  "scripts": {
+    "lint": "eslint tasks test src/ol examples config",
+    "pretest": "npm run lint && npm run typecheck",
+    "test-browser": "npm run karma -- --single-run --log-level error",
+    "test": "npm run test-browser -- --force",
+    "karma": "karma start test/browser/karma.config.cjs",
+    "start": "npm run serve-examples",
+    "serve-examples": "webpack serve --config examples/webpack/config.mjs --mode development",
+    "build-examples": "shx rm -rf build/examples && webpack --config examples/webpack/config.mjs --mode production",
+    "build-package": "npm run build-full && npm run generate-types && node tasks/prepare-package.js",
+    "build-index": "shx rm -f build/index.js && npm run transpile && node tasks/generate-index.js",
+    "build-full": "shx rm -rf build/full && npm run build-index && npx rollup --config config/rollup-full-build.js",
+    "generate-types": "tsc --project config/tsconfig-build.json --declaration --declarationMap --emitDeclarationOnly --outdir build/ol",
+    "transpile": "shx rm -rf build/ol && shx mkdir -p build/ol && shx cp -rf src/ol build",
+    "typecheck": "tsc --pretty",
+    "apidoc-debug": "shx rm -rf build/apidoc && node --inspect-brk=9229 ./node_modules/jsdoc/jsdoc.js --readme config/jsdoc/api/index.md --configure config/jsdoc/api/conf.json --package package.json --destination build/apidoc",
+    "apidoc": "shx rm -rf build/apidoc && jsdoc --readme config/jsdoc/api/index.md --configure config/jsdoc/api/conf.json --package package.json --destination build/apidoc"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/m-mohr/ol-stac.git"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/m-mohr/ol-stac/issues"
+  },
+  "dependencies": {
+    "ol": "^7.0.0",
+    "stac-js": "0.0.8"
+  },
+  "devDependencies": {
+    "@metalsmith/in-place": "^5.0.0",
+    "@metalsmith/layouts": "^2.5.1",
+    "@metalsmith/markdown": "^1.6.0",
+    "@octokit/rest": "^20.0.1",
+    "@openlayers/eslint-plugin": "^4.0.0",
+    "@rollup/plugin-commonjs": "^25.0.0",
+    "@rollup/plugin-node-resolve": "^15.0.0",
+    "@rollup/plugin-terser": "^0.4.3",
+    "copy-webpack-plugin": "^11.0.0",
+    "es-main": "^1.0.2",
+    "eslint": "^8.0.1",
+    "eslint-config-openlayers": "^18.0.0",
+    "expect.js": "0.3.1",
+    "front-matter": "^4.0.0",
+    "fs-extra": "^11.1.0",
+    "handlebars": "4.7.8",
+    "jsdoc": "4.0.2",
+    "jsdoc-plugin-intersection": "^1.0.4",
+    "jsdoc-plugin-typescript": "^2.2.0",
+    "json-stringify-safe": "^5.0.1",
+    "jstransformer-handlebars": "^1.2.0",
+    "karma": "^6.3.8",
+    "karma-chrome-launcher": "^3.1.0",
+    "karma-mocha": "2.0.1",
+    "karma-source-map-support": "^1.4.0",
+    "karma-webpack": "^5.0.0",
+    "marked": "7.0.2",
+    "metalsmith": "^2.5.0",
+    "mocha": "10.2.0",
+    "pixelmatch": "^5.1.0",
+    "pngjs": "^7.0.0",
+    "proj4": "2.9.0",
+    "puppeteer": "21.0.3",
+    "rollup": "^3.28.0",
+    "rollup-plugin-external-globals": "^0.8.0",
+    "semver": "^7.3.7",
+    "shx": "^0.3.2",
+    "sinon": "^15.0.0",
+    "source-map-loader": "^4.0.0",
+    "typescript": "5.1.6",
+    "walk": "^2.3.9",
+    "webpack": "^5.27.2",
+    "webpack-cli": "^5.0.0",
+    "webpack-dev-middleware": "^6.0.0",
+    "webpack-dev-server": "^4.0.0-beta.2",
+    "webpack-sources": "^3.2.0",
+    "yargs": "^17.0.0"
+  },
+  "eslintConfig": {
+    "extends": "openlayers",
+    "plugins": [
+      "@openlayers"
+    ],
+    "rules": {
+      "jsdoc/no-bad-blocks": "off",
+      "import/no-commonjs": "error",
+      "@openlayers/no-exclusive-tests": [
+        "error",
+        {
+          "include": "test/**/*.test.js"
+        }
+      ]
+    }
+  },
+  "browserslist": [
+    "> 1%",
+    "last 2 versions",
+    "not dead"
+  ]
+}

package/site/build.js

@@ -0,0 +1,26 @@
+import Metalsmith from 'metalsmith';
+import inPlace from '@metalsmith/in-place';
+import layouts from '@metalsmith/layouts';
+import markdown from '@metalsmith/markdown';
+import {dirname} from 'node:path';
+import {env} from 'node:process';
+import {fileURLToPath} from 'node:url';
+
+const baseDir = dirname(fileURLToPath(import.meta.url));
+
+const builder = Metalsmith(baseDir)
+  .source('./src')
+  .destination('./build')
+  .clean(true)
+  .metadata({
+    version: env.OL_VERSION || 'dev',
+  })
+  .use(inPlace({transform: 'handlebars'}))
+  .use(markdown())
+  .use(layouts());
+
+builder.build(async (err) => {
+  if (err) {
+    throw err;
+  }
+});

package/site/layouts/default.hbs

@@ -0,0 +1,78 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name='viewport' content='width=device-width, initial-scale=1.0'>
+    <title>OL STAC - {{ title }}</title>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.28.0/components/prism-core.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.28.0/plugins/autoloader/prism-autoloader.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.28.0/plugins/toolbar/prism-toolbar.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.28.0/plugins/copy-to-clipboard/prism-copy-to-clipboard.min.js"></script>
+    <link rel="stylesheet" type="text/css" href="https://fonts.googleapis.com/css?family=Quattrocento+Sans:400,400italic,700" crossorigin="anonymous">
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/css/bootstrap.min.css" crossorigin="anonymous">
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@6.1.2/css/fontawesome.min.css" crossorigin="anonymous">
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@6.1.2/css/solid.css" crossorigin="anonymous">
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@6.1.2/css/brands.css" crossorigin="anonymous">
+    <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/ol/ol.css">
+    <link rel="stylesheet" type="text/css" href="/ol-stac/theme/site.css">
+{{#each head}}
+    {{{ this }}}
+{{/each}}
+  </head>
+  <body>
+    <header class="navbar navbar-expand-md navbar-dark mb-3 px-3 py-0 fixed-top" role="navigation">
+      <a class="navbar-brand" href="/">OL STAC</a>
+      <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#olmenu" aria-controls="olmenu" aria-expanded="false" aria-label="Toggle navigation">
+        <span class="navbar-toggler-icon"></span>
+      </button>
+
+      <!-- menu items that get hidden below 768px width -->
+      <nav class="collapse navbar-collapse" id="olmenu">
+        <ul class="nav navbar-nav ms-auto">
+          <li class="nav-item dropdown">
+            <a class="nav-link dropdown-toggle" href="#" id="docdropdown" role="button" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Docs</a>
+            <div class="dropdown-menu dropdown-menu-end mb-3" aria-labelledby="docdropdown">
+              <a class="dropdown-item" href="/ol-stac/doc/">Docs</a>
+              <div class="dropdown-divider"></div>
+                <a class="dropdown-item" href="/ol-stac/doc/quickstart.html"><i class="fa fa-check fa-fw me-2 fa-lg"></i>Quick Start</a>
+                <a class="dropdown-item" href="/ol-stac/doc/faq.html"><i class="fa fa-question fa-fw me-2 fa-lg"></i>FAQ</a>
+                <a class="dropdown-item" href="/ol-stac/doc/tutorials/"><i class="fa fa-book fa-fw me-2 fa-lg"></i>Tutorials</a>
+            </div>
+          </li>
+          <li class="nav-item"><a class="nav-link" href="/ol-stac/en/latest/examples/">Examples</a></li>
+          <li class="nav-item dropdown">
+            <a class="nav-link dropdown-toggle" href="#" id="apidropdown" role="button" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
+              <i class="fa fa-sitemap me-1"></i>API
+            </a>
+            <div class="dropdown-menu dropdown-menu-end mb-3" aria-labelledby="apidropdown">
+              <a class="dropdown-item" href="/ol-stac/en/latest/apidoc/"><i class="fa fa-sitemap fa-fw me-2 fa-lg"></i>{{ version }} (latest)</a>
+            </div>
+          </li>
+          <li class="nav-item dropdown">
+            <a class="nav-link dropdown-toggle" href="#" id="codedropdown" role="button" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Code</a>
+            <div class="dropdown-menu dropdown-menu-end mb-3" aria-labelledby="codedropdown">
+              <a class="dropdown-item" href="https://github.com/m-mohr/ol-stac"><i class="fab fa-github fa-fw me-2 fa-lg"></i>Repository</a>
+              <a class="dropdown-item" href="/ol-stac/download/"><i class="fa fa-download fa-fw me-2 fa-lg"></i>Download</a>
+            </div>
+          </li>
+        </ul>
+      </nav>
+    </header>
+
+{{#if uncontained}}
+    {{{ contents }}}
+{{else}}
+    <div class="container">
+      {{{ contents }}}
+    </div>
+{{/if}}
+    <footer>
+      Code licensed under the <a href='https://www.tldrlegal.com/license/apache-license-2-0-apache-2-0'>Apache 2.0</a>.
+      All documentation <a href='http://creativecommons.org/licenses/by/3.0/'>CC BY 3.0</a>.
+    </footer>
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/js/bootstrap.bundle.min.js"></script>
+{{#each scripts}}
+    {{{this}}}
+{{/each}}
+  </body>
+</html>

package/site/src/doc/faq.md

@@ -0,0 +1,8 @@
+---
+title: Frequently Asked Questions (FAQ)
+layout: default.hbs
+---
+
+# Frequently Asked Questions (FAQ)
+
+tbd

package/site/src/doc/index.md

@@ -0,0 +1,22 @@
+---
+title: Documentation
+layout: default.hbs
+---
+
+# Documentation
+
+If you're eager to get your first OpenLayers map on a page, dive into the [quick start](./quickstart.html).
+
+For a more in-depth overview of OpenLayers core concepts, check out the [tutorials](./tutorials/).
+
+Make sure to also check out the [OpenLayers workshop](/workshop/).
+
+Find additional reference material in the [API docs](/en/latest/apidoc/) and [examples](/en/latest/examples/).
+
+# Frequently Asked Questions (FAQ)
+
+We have put together a document that lists [Frequently Asked Questions (FAQ)](./faq.html) and our answers. Common problems that may arise when using OpenLayers are explained there, and chances are you'll find an appropriate solution in this document.
+
+# More questions?
+
+If you cannot find an answer in the documentation or the FAQ, you can search [Stack Overflow](https://stackoverflow.com/questions/tagged/openlayers). If you cannot find an answer there, ask a new question there, using the tag 'openlayers'.