opensearchcon-new.js

const {
     existsSync 
} = require('node:fs');
const fs = require('node:fs/promises');
const path = require('path');
const matter = require('gray-matter');
const YAML = require('yaml');

/**
 * Output usage information to the user and exit.
 * Optionally a warning message about invalid user input and a non-zero exit status code can be provided.
 * @param {string} warnMessage Optional warning message to output to the user to indicate why the program is exiting prematurely.
 * @param {number} exitCode Optional program exit code useful when printing a warning message exiting because of user input error; default is 0.
 */
function exitWithUsage(warnMessage = '', exitCode = 0) {
    if (warnMessage !== '') {
        console.warn(warnMessage);
    }
    console.info('Creates the required file system boilerplate for a new OpenSearch Con.');
    console.info('Usage $ npm run opensearchcon:new -- FOUR_DIGIT_YEAR_ARG LOCATION_NAME[ COMMA_SEPARATED_LIST_OF_SECTIONS]');
    console.info('For Example to create a new opensearchcon file system boilerplate for 2024 in Europe with all available sections:');
    console.info("\t$ npm run opensearchcon:new -- 2024 europe speakers,sessions,exhibitors,workshops,unconference");
    console.info("\n\nIf the COMMA_SEPARATED_LIST_OF_SECTIONS is omitted then the default set of exhibitors,speakers,sessions,unconferenceworkshops is used.");
    console.info("\tThe sections list must include at least exhibitors, sessions, and speakers. The unconference, and workshops are considered optional even though they are present by default.");
    console.info("\n\nA valid location name consists of patterns of word character class strings optionally separated by a hyphen.")
    console.info("\tFor example: north-america, or europe");
    console.info("\n\nThe conference_id will be generated by concatenation of the location name to the year separated by a hyphen");
    console.info("\tFor example: 2024-europe, or 2024-north-america");
    process.exit(exitCode);
}

/**
 * Returns a boolean indicating whether or not the `year` argument is or is not a 4 digit year.
 * @param {string} year A string containing the user input for the conference year.
 * @returns {boolean}
 */
function isValidYear(year) {
    const yearPattern = /^\d{4}$/;
    return yearPattern.test(year);
}

/**
 * Returns a boolean indicating whether or not the `location` argument conforms to acceptable
 * input values for a conference location. Acceptable formats consists of sequences of 
 * English alphabet characters optionally separated by a hypen. For example 'north-america',
 * or simply 'europe'. Case is ignored, however the string is expected to be trimmed with no
 * white space on either end. There is no minimum length greater than 1 as it is unclear how
 * to intelligently determine what might be a meaningful minimum length.
 * @param {string} location A string containing the name of the conference location.
 * @returns {boolean}
 */
function isValidLocationName(location) {
    const locationPattern = /^[a-z]+([a-z]+)*$/i;
    return locationPattern.test(location);
}

/**
 * Returns a boolean indicating whether or not `sections` argument value contains an acceptable
 * comma separated list of conference section names. Acceptable values are as follows:
 * 
 * * exhibitors
 * * sessions
 * * speakers
 * * unconference
 * * workshops
 * 
 * Of the 5 sections, only exhibitors, sessions, and speakers are required.
 * For clarity, this choice was made given that the 2022 conference only has those three sections. 
 * Whereas 2023 has all 5. 
 * The string is expected to consist of only lower case characters with no spaces before or after
 * the comma separaters. Keeping requirements narrow just keeps things simple.
 * @param {string} sections A string containing a comma separated list of conference section names.
 * @returns {boolean}
 */
function isValidSectionList(sections) {
    const sectionList = sections?.split?.(',') ?? [];
    if (sectionList.length === 0) {
        return false;
    }
    const optionalList = ['unconference', 'workshops'];
    const requiredList = ['exhibitors', 'sessions', 'speakers'];
    const defaultList = [...requiredList, ...optionalList];
    sectionList.sort();
    if (sectionList.length === defaultList.length) {
        const hasAllSections = sectionList.every((value, index) => value === defaultList[index]);
        return hasAllSections;
    }
    const hasRequiredSections = requiredList.every(value => sectionList.includes(value));
    return hasRequiredSections;
}

/**
 * Returns a copy of the `s` argument value the first character ensured to be upper case.
 * If the `s` argument is empty, or not a string then it is returned directly.
 * @param {string} s A non-zero length string.
 * @returns {string}
 */
function upperCaseFirstChar(s) {
    if (s !== '') {
        const ucFirst = `${s.charAt(0).toUpperCase()}${s.substring(1)}`;
        return ucFirst;
    }
    return s;
}

/**
 * Returns a readable transformation of the conference location name as provided as a runtime
 * command line argument. See the description of the `isValidLocationName` function for details
 * on what is considered valid parameter value format.
 * The returned form is each alphabetical (English) component in the program input for location name
 * changed so that its first character is upper case. 
 * For example, where `location` === 'europe' then the return value will be 'Europe'.
 * Where 'location' === 'north-america' then the return value will be 'North America'.
 * The value provided on the command line will be interpolated into URL strings and this value
 * will be interpolated into menu item text, and breadcrumb text, etc.
 * @param {string} location A string containing the name of the location of a conference.
 * @returns {string}
 * @see {isValidLocationName}
 */
function getReadableLocationName(location) {
    const readable = location.split(/[^a-z]+/ig).map(upperCaseFirstChar).join(' ');
    return readable;
}

/**
 * Returns on object with the runtime arguments provided by the user on the CLI for conference year,
 * location name, and optionally which conference sections to include in the file system boilerplate
 * created by this program.
 * The `argv` argument is treated the same as if it is the `process.argv` provided by the NodeJS runtime.
 * That is to say that it is an array of strings where indices 0, and 1 are the path to the NodeJS executable,
 * and this script respectfully. With the meaningful program arguments provided in indices 2, 3, and optionally 4
 * if necessary as the year, location, and sections respectfully.
 * If no value is specified fo conference sections (argv[4]) then the default is assumed which includes
 * all 5 possible sections.
 * The returned object contains the following properties:
 * 
 * * conferenceYear
 * * conferenceLocation
 * * conferenceSections
 * 
 * If any of the input values do not pass validation then a warning message is printed, followed by 
 * the usage information text, and the program exits with exit code 1.
 * @param {string[]} argv Program execution command line arguments as expected to be provided by the NodeJS runtime value in `process.argv`.
 * @returns {object}
 * @see {isValidSectionList}
 * @see {@link https://nodejs.org/api/process.html#processargv}
 */
function getInputArgs(argv) {
    const defaultSections = "exhibitors,speakers,sessions,unconference,workshops";
    const [, , conferenceYear, conferenceLocation, conferenceSections = defaultSections] = argv;
    if (!isValidYear(conferenceYear)) {
        exitWithUsage(`Invalid input value for conference year given: "${conferenceYear}"`, 1);
    }
    if (!isValidLocationName(conferenceLocation)) {
        exitWithUsage(`Invalid input value for conference location given: "${conferenceLocation}"`, 1);
    }
    if (!isValidSectionList(conferenceSections)) {
        exitWithUsage(`Invalid input value for conference sections list given: "${conferenceSections}"`, 1);
    }
    return {
        conferenceYear,
        conferenceLocation,
        conferenceSections,
    };
}

/**
 * Reads the contents of a Markdown file that contains Front Matter optionally followed by Markdonw / HTML content
 * and returns a Promise resolved with an object representation of that data utlizing the `gray-matter` NPM package.
 * The returned object among other things will contain two properties meaningful to this program:
 * 
 * * data
 * * content
 * 
 * The `data` property will be a JavaScript object that represents the parsed YAML structure in the Front Matter.
 * The `content` property will be a string that contains the Markdown / HTML text below the Front Matter.
 * @param {string} filePath A string containing a fully qualified file system path to a Markdown file to read.
 * @returns {Promise<object>}
 * @see {@link https://www.npmjs.com/package/gray-matter}
 */
async function loadFrontMatterData(filePath) {
    const fileData = await fs.readFile(filePath, { encoding: 'utf8' });
    const parsedData = matter(fileData);
    return parsedData;
}

/**
 * Write Front Matter and Markdown content to disk at a specifed path.
 * The returned Promise is resolved with `undefined` upon success.
 * The Markdown content, and Front Matter data are stringified utilizing the gray-matter NPM package.
 * @param {object} frontMatterData An object defining the Front Matter data and Markdown content to serialize to disk.
 * @param {string} filePath A string containing the fully qualified file system path to write.
 * @returns {Promise<undefined>}
 * @see {@link https://www.npmjs.com/package/gray-matter}
 */
async function writeObjectAsFrontMatter(frontMatterData, filePath) {
    const fileData = matter.stringify(frontMatterData.content, frontMatterData.data);
    return await fs.writeFile(filePath, fileData, 'utf8');
}

/**
 * Returns an object that maps section names to the respective file system paths of the Jekyll 
 * Collection directories for each section.
 * Note that whereas the section name "speakers" is a section of a conference content set with its
 * own listing page. However, the referenced speakers are actually entries in the site "Community Members"
 * collection with the "conference_speaker" user persona / role, and with a set of conference IDs that
 * include that which identifies the conference being setup by this program execution.
 * The returned object contains each section name as a property whos value is the path to where the 
 * collection items will be written.
 * @param {string[]} sections An array of conference section names.
 * @param {string} baseDir The base directory from which to construct the returned path names.
 * @returns {object}
 */
function createSectionCollectionsPaths(sections, baseDir) {
    const collectionsPaths = sections.reduce((carry, current) => {
        const collectionPath = current !== 'speakers' ? 
            path.join(baseDir, `_opensearchcon_${current}`) : 
            path.join(baseDir, '_community_members');
        return {
            ...carry,
            [current]: collectionPath,
        };
    }, {});
    return collectionsPaths;
}

/**
 * Returns an object that maps section names to a pair of file system directory paths.
 * Each section name maps two properties:
 * 
 * * pagePath
 * * sampleDataPath
 * 
 * The `pagePath` value is the file system path for where the `index.md` file will be created for the mapped section.
 * The `sampleDataPath` is the file system path to the related '_sample-index.md' file that contains the sample Front Matter
 * and possible Markdown / HTML content boilerplate that will be copied and modified to be written at the `pagePath` location.
 * @param {string[]} sections An array of conference section names.
 * @param {string} conferenceBaseDir The file system path to the conference pages within the ./events/opensearchcon/.. directory.
 * @param {string} sampleBaseDir The file system path to the sample conference pages with `_sample.md` files.
 * @returns {object}
 */
function createEventPagesPaths(sections, conferenceBaseDir, sampleBaseDir) {
    const landingPagePath = conferenceBaseDir;
    const landingSamplePath = path.join(sampleBaseDir, '_sample-index.md');
    const pagesPaths = sections.reduce((carry, current) => {
        const pagePath = path.join(conferenceBaseDir, current);
        const sampleDataPath = path.join(sampleBaseDir, `_sample-year-location-${current}`, '_sample-index.md');
        return {
            ...carry,
            [current]: {
                pagePath,
                sampleDataPath,
            },
        };
    }, {
        landingPage: {
            pagePath: landingPagePath,
            sampleDataPath: landingSamplePath,
        },
    });
    return pagesPaths;
}

/**
 * Creates the file system structure and boilerplate for the conference section pages.
 * For each section being created (exhibitors, sessions, etc) the appropriate directory 
 * is created and within it an 'index.md' file will be written with content copied from the corresponding
 * '_sample-index.md' file using values defined in `boilerplateOverrides` to override the default sample values.
 * The returned Promise is resolved with `undefined` upon success.
 * See the `createSectionCollectionsPaths` function for the expected shape of `pagesPathsConfig`.
 * The `boilerplateOverrides` object is expected to be a mapping of section name to whatever key/value
 * pairs are meaningful for the corresponding section.
 * @param {object} pagesPathsConfig An object that maps conference section names to a pair of file system paths for source sample data, and where to write the page content.
 * @param {object} boilerplateOverrides An object that defines values to override data in each section's respective '_sample-index.md' sample data file.
 * @returns {Promise<undefined>}
 * @see {createSectionCollectionsPaths}
 */
async function writeEventPagesBoilerplate(pagesPathsConfig, boilerplateOverrides) {
    await Promise.all(
        Object.entries(pagesPathsConfig).map(async ([section, paths]) => {
            const { pagePath, sampleDataPath } = paths;
            if (!existsSync(pagePath)) {
                const createdDir = await fs.mkdir(pagePath, { recursive: true });
                console.log(`Created events subdir ${createdDir}`);
            }
            console.log(`Loading sample section data from ${sampleDataPath}`);
            const sectionSampleData = await loadFrontMatterData(sampleDataPath);
            const boilerplateData = {
                data: {
                    ...sectionSampleData.data,
                    ...boilerplateOverrides[section].data,
                },
                content: boilerplateOverrides[section].hasOwnProperty('content') ? boilerplateOverrides[section].content : sectionSampleData.content,
            };
            const pageFilePath = path.join(pagePath, 'index.md');
            console.log(`Writing events section page: ${pageFilePath}`);;
            return await writeObjectAsFrontMatter(boilerplateData, pageFilePath);
        })
    );
}

/**
 * Write placeholder collection entries for each section. Along with the appropriate files within `./events/opensearchcon/YEAR/LOCATION/...`
 * there are also placeholder entries in the Jekyll Collections' directories with placeholder content mapped to the
 * conference's corresponding "conference_id" ready to be modified for the new conference pages.
 * Within each collection directory dummy content will be copied from its "_sample.md" file with values overridden
 * with values provided by the `boilerplateOverrides` object.
 * The returned Promise is resolved with `undefined` upon success.
 * @param {object} collectionPathsConfig An object mapping section names to the file system paths of the corresponding sections' Jekyll collection placeholder content entries to be written.
 * @param {object} boilerplateOverrides An object mapping section names to whatever meaningful values needed to override from the collections' "_sample.md" file.
 * @returns {Promise<undefined>}
 */
async function writeCollectionPagesBoilerplate(collectionPathsConfig, boilerplateOverrides) {
    await Promise.all(
        Object.entries(collectionPathsConfig).map( async ([section, sectionPath]) => {
            const overrides = boilerplateOverrides[section];
            if (section !== 'speakers') {
                const conferenceId = overrides.data.conference_id;
                const placeholderEntryFilename = `${conferenceId}-placeholder-${section}.md`;
                const placeholderEntryPath = path.join(sectionPath, placeholderEntryFilename);
                const sampleDataPath = path.join(sectionPath, '_sample.md');
                console.log(`Loading sample collection data from ${sampleDataPath}`);
                const sampleData = await loadFrontMatterData(sampleDataPath);
                const boilerplateData = {
                    data: {
                        ...sampleData.data,
                        ...overrides.data,
                    },
                    content: overrides.hasOwnProperty('content') ? overrides.content : sampleData.content,
                };
                console.log(`Writing placeholder collection entry at ${placeholderEntryPath}`);
                return await writeObjectAsFrontMatter(boilerplateData, placeholderEntryPath);
            } else {
                return Promise.all(overrides.map(async (speakerOverride) => {
                    const conferenceId = speakerOverride.data.conference_id;
                    const placeholderEntryFilename = `${speakerOverride.data.short_name}.md`;
                    const placeholderEntryPath = path.join(sectionPath, placeholderEntryFilename);
                    const sampleDataPath = path.join(sectionPath, '_sample.md');
                    console.log(`Loading sample collection data from ${sampleDataPath}`);
                    const sampleData= await loadFrontMatterData(sampleDataPath);
                    const boilerplateData = {
                        data: {
                            ...sampleData.data,
                            ...speakerOverride.data,
                        },
                        content: speakerOverride.hasOwnProperty('content') ? speakerOverride.content : sampleData.content,
                    };
                    console.log(`Writing placeholder collection entry at ${placeholderEntryPath}`);
                    return await writeObjectAsFrontMatter(boilerplateData, placeholderEntryPath);
                }));
            }
        })
    );
}

/**
 * Return an object that defines an override for a page's or collection entry's breadcrumbs Front Matter configuration.
 * The returned object always defines the 'community' icon, and an array of (title, url) pairs for the following trail of breadcrumbs:
 * 
 * 1. The OpenSearchCon landing page
 * 2. The landing page for the specified year.
 * 3. The landing page for the specified year + location.
 * 
 * Additional items can be appended if desired by passing an array for the `additionalItems` parameter.
 * @param {string} year The 4 digit conference year.
 * @param {string} location The CLI argument value for the conference location; eg 'north-america'.
 * @param {string} readableLocation The readable form of the conference location; eg 'North America'.
 * @param {object[]} additionalItems Any additional breadcrumb items to append to the default breadcrumbs.
 * @returns {object}
 */
function createBreadcrumbItemsOverride(year, location, readableLocation, additionalItems = []) {
    const breadcrumbs = {
        icon: 'community',
        items: [{
            title: 'OpenSearchCon',
            url: '/events/opensearchcon/index.html',
        }, {
            title: year,
            url: `/events/opensearchcon/${year}/index.html`,
        }, {
            title: readableLocation,
            url: `/events/opensearchcon/${year}/${location}/inde.html`,
        }, ...additionalItems],
    };
    return breadcrumbs;
}

/**
 * Return a configuration array for a conference landing page's button stack linking to each conference section.
 * The returned array contains a set of objects that pair (name, url) for each section.
 * @param {string[]} sections Array of conference section names.
 * @param {string} year The 4 digit year of the conference.
 * @param {string} location The URL-friendly location name.
 * @returns {object[]}
 */
function createSectionsButtonStackOverrides(sections, year, location) {
    const buttonStackConfig = sections.reduce((carry, current) => {
        const url = `/events/opensearchcon/${year}/${location}/${current}/index.html`;
        const label = upperCaseFirstChar(current);
        carry.push({
            label,
            url,
        });
        return carry;
    }, []);
    return buttonStackConfig;
}

/**
 * Return an object defining the structure for creating an entry in the site's top navigation menu configuration.
 * The returned object defines the following properties:
 * 
 * * label: Menu item text in the form of "${year} ${readableLocation"; eg "2024 North America".
 * * url: The URI path to the conference landing page; eg "/events/opensearchcon/2024/north-america/index.html".
 * * children: An array of (label, url) pairs for each section of the conference
 * 
 * @param {string} year The 4 digit year of the conference; eg label: "Sessions", url: "/events/opensearchcon/2024/north-america/sessions/index.html".
 * @param {string} location The URL-friendly form of the location name.
 * @param {string} readableLocation The readable form of the location name used in menu item text.
 * @param {string[]} sections An array of conference section name strings.
 * @returns {object}
 */
function createNavigationMenuItems(year, location, readableLocation, sections) {
    const parentLabelText = `${year} ${readableLocation}`;
    const conferenceBaseUrl = `/events/opensearchcon/${year}/${location}`;
    const menuItems = {
        label: parentLabelText,
        url: `${conferenceBaseUrl}/index.html`,
        children: sections.map(sectionName => ({
            label: `${upperCaseFirstChar(sectionName)}`,
            url: `${conferenceBaseUrl}/${sectionName}/index.html`,
        })),
    };
    return menuItems;
}

/**
 * Return a Promise resolved with an object representation of the YAML contents of a specified file system path.
 * @param {string} yamlPath File system path to a YAML file to be read and parsed into an object.
 * @returns {Promise<object>}
 * @see {@link https://www.npmjs.com/package/yaml}
 */
async function loadYamlDataAsJSObject(yamlPath) {
    const yamlData = await fs.readFile(yamlPath, 'utf8');
    const jsonData = YAML.parse(yamlData);
    return jsonData;
}

/**
 * Serialize an object representation of the site's top navigation menu configuration in YAML format.
 * The file will be written to the path formed by concatenating '/_data/top_nav.yml' to the value of
 * the `baseDir` argument.
 * The returned Promise is resolved with `undefined` upon success.
 * @param {string} baseDir File system path to the site repo working directory that contains the '_data' collection as a subdirectory.
 * @param {object} jsonData JavaScript object to serialize to disk in YAML format.
 * @returns {Promise<undefined>}
 * @see {@link https://www.npmjs.com/package/yaml}
 */
async function writeSiteTopNavMenu(baseDir, jsonData) {
    const topNavConfigPath = path.join(baseDir, '_data', 'top_nav.yml');
    console.log(`Writing top navigation menu configuration at "${topNavConfigPath}"`);
    const yamlData = YAML.stringify(jsonData);
    return await fs.writeFile(topNavConfigPath, yamlData, 'utf8');
}

/**
 * Read the site navigation configuration YAML file and return it parsed into a JavaScript object.
 * The path to the YAML file to read and whos contents are to be parsed is formed by concatenating
 * '/_data/top_nav.yml' to the value of the `baseDir` argument.
 * The returned Promise is resolved with an object representing the structure defined in './_data/top_nav.yml'.
 * Which is an array of items that contain some form of the following properties:
 * 
 * * label: Menu item label text.
 * * url: Relative or fully qualified URL for the menut item.
 * * children: Optional array of sub menu items following the same shape to form a tree of navigation items.
 * 
 * @param {string} baseDir File system path to the site repo working directory that contains the '_data' collection as a subdirectory.
 * @returns {Promise<object>}
 */
async function readSiteTopNavMenu(baseDir) {
    const topNavConfigPath = path.join(baseDir, '_data', 'top_nav.yml');
    console.log(`Reading top navigation menu configuration at "${topNavConfigPath}"`)
    const topNavMenuItems = await loadYamlDataAsJSObject(topNavConfigPath);
    return topNavMenuItems;
}

/**
 * Insert the menu item object into the site's top navigation menu structure as a child of a specified parent
 * at a specified index within the parent's `children` array.
 * Indices are expected to be zero-based.
 * The returned object is the modified `topNavMenuItems` object which is modified in place.
 * @param {object} topNavMenuItems An object defining the site top navigation menu structure as parsed from the YAML in '_data/top_nav.yml'.
 * @param {object} conferenceMenu The menu item and children for the new conference pages.
 * @param {number} parentIndex The index of the top level parent menu item whos `children` will be used as the insertion target to contain the conference menu.
 * @param {number} insertionIndex The index within the parent's `children` array to insert the conference menu.
 * @returns {object}
 */
function insertConferenceMenuItems(topNavMenuItems, conferenceMenu, parentIndex, insertionIndex) {
    const parentMenuItem = topNavMenuItems.items[parentIndex];
    const parentChildren = parentMenuItem.children;
    parentChildren.splice(insertionIndex, 0, conferenceMenu);
    return topNavMenuItems;
}

/**
 * Update the configuration data for the site's top navigation menu as defined within './_data/top_nav.yml'
 * to contain a new menu item for the new conference with sub-menu items for each included section.
 * The returned Promise is resolved with `undefined` upon success.
 * @param {string} baseDir A string defining the file system path to the repo base working directory.
 * @param {string} year A string defining the 4 digit year of the new conference.
 * @param {string} location A string defining the URL-friendly location name of the new conference.
 * @param {string} readableLocation A string defining the readable title-friendly, or label-text-friendly location name of the new conference.
 * @param {string[]} sectionNames An array of strings defining the conference section names.
 * @returns {Promise<undefined>}
 * @see {createNavigationMenuItems}
 * @see {readSiteTopNavMenu}
 * @see {insertConferenceMenuItems}
 * @see {writeSiteTopNavMenu}
 */
async function updateTopNavMenu(baseDir, year, location, readableLocation, sectionNames) {
    const conferenceMenu = createNavigationMenuItems(year, location, readableLocation, sectionNames);
    const currentSiteNavMenu = await readSiteTopNavMenu(baseDir);
    const OPENSEARCHCON_TOP_MENU_INDEX = 0;
    const OPENSEARCHCON_ARCHIVE_MENU_INDEX = 1;
    const modifiedSiteNavMenu = insertConferenceMenuItems(
        currentSiteNavMenu,
        conferenceMenu,
        OPENSEARCHCON_TOP_MENU_INDEX,
        OPENSEARCHCON_ARCHIVE_MENU_INDEX
    );
    console.log('Writing updated site navigation menu configuration.');
    await writeSiteTopNavMenu(baseDir, modifiedSiteNavMenu);
}

/**
 * Return an array of object used to override properties in sample Front Matter for Community Members
 * configured with the `conference_speaker` user persona / role, one who is a keynote speaker, and one
 * who is not.
 * @param {string} conferenceId A string defining the conference ID.
 * @param {string} conferenceYear A string defining the 4 digit year of the conference.
 * @param {string} conferenceLocation A string defining the URL-friendly conference location name.
 * @param {string} readableLocationName A string defining the label/title friendly readable conference location name.
 * @returns {object[]}
 */
function createPlaceholderSpeakersOverrides(conferenceId, conferenceYear, conferenceLocation, readableLocationName) {
    const placeholderSpeakers = [{
        short_name: `placeholder-speaker-${conferenceId}-1`,
        name: `Placeholder Speaker ${conferenceYear} ${readableLocationName} 1`,
        photo: '/assets/media/community/members/no-image-available.svg',
        primary_title: `Placeholder Speaker ${conferenceYear} ${readableLocationName} 1`,
        title: `OpenSearch Project Community Member: Placeholder Speaker ${conferenceYear} ${readableLocationName} 1`,
        breadcrumbs: createBreadcrumbItemsOverride(conferenceYear, conferenceLocation, readableLocationName, [{
            title: 'Speakers',
            url: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/speakers/index.html`,
        }, {
            title: `Placeholder Speaker ${conferenceYear} ${readableLocationName} 1`,
            url: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/placeholder-speaker-1.html`,
        }]),
        job_title_and_company: 'Job title at Company',
        keynote_speaker: [conferenceId],
        session_track: [{
            conference_id: conferenceId,
            name: 'Community',
        }],
        permalink: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/placeholder-speaker-1.html`,
        conference_id: [conferenceId],
    }, {
        short_name: `placeholder-speaker-${conferenceId}-2`,
        name: `Placeholder Speaker ${conferenceYear} ${readableLocationName} 2`,
        photo: '/assets/media/community/members/no-image-available.svg',
        primary_title: `Placeholder Speaker ${conferenceYear} ${readableLocationName} 2`,
        title: `OpenSearch Project Community Member: Placeholder Speaker ${conferenceYear} ${readableLocationName} 2`,
        breadcrumbs: createBreadcrumbItemsOverride(conferenceYear, conferenceLocation, readableLocationName, [{
            title: 'Speakers',
            url: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/speakers/index.html`,
        }, {
            title: `Placeholder Speaker ${conferenceYear} ${readableLocationName} 1`,
            url: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/placeholder-speaker-2.html`,
        }]),
        job_title_and_company: 'Job title at Company',
        keynote_speaker: false,
        session_track: [{
            conference_id: conferenceId,
            name: 'Community',
        }],
        permalink: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/placeholder-speaker-2.html`,
        conference_id: [conferenceId],
    }];
    return placeholderSpeakers;
}

/**
 * Retun an object used to override properties in sample Front Matter and Markdown for the various section
 * pages, and the conference landing page.
 * @param {string} conferenceId A string defining the conference ID
 * @param {string} conferenceYear A string defining the 4 digit year of the conference
 * @param {string} conferenceLocation A string defining the URL-friendly conference location name.
 * @param {string} readableLocationName A string defining the labe/title text friendly readable conference location name.
 * @param {string[]} splitSections An array of strings defining the conference section names.
 * @returns {object}
 */
function createBoilerplateSectionsPagesOverrides(conferenceId, conferenceYear, conferenceLocation, readableLocationName, splitSections) {
    const sectionPagesOverrides = {
        landingPage: {
            data: {
                title: `OpenSearchCon ${conferenceYear}: ${readableLocationName}`,
                primary_title: `OpenSearchCon ${conferenceYear}: ${readableLocationName}`,
                breadcrumbs: createBreadcrumbItemsOverride(conferenceYear, conferenceLocation, readableLocationName),
                conference_id: conferenceId,
                permalink: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/index.html`,
                redirect_from: `/events/opensearchcon/${conferenceYear}/index.html`,
                conference_sections_button_stack: createSectionsButtonStackOverrides(splitSections, conferenceYear, conferenceLocation),
            },
        },
        exhibitors: {
            data: {
                title: `OpenSearchCon ${conferenceYear}: ${readableLocationName} Exhibitors`,
                primary_title: `OpenSearchCon ${conferenceYear}: ${readableLocationName} Exhibitors`,
                breadcrumbs: createBreadcrumbItemsOverride(
                    conferenceYear,
                    conferenceLocation,
                    readableLocationName, [{ 
                        title: 'Exhibitors', 
                        url: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/exhibitors/index.html`
                    }]
                ),
                conference_id: conferenceId,
                permalink: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/exhibitors/index.html`,
            },
        },
        sessions: {
            data: {
                title: `OpenSearchCon ${conferenceYear}: ${readableLocationName} Session Lineup`,
                primary_title: `OpenSearchCon ${conferenceYear}: ${readableLocationName} Session Lineup`,
                breadcrumbs: createBreadcrumbItemsOverride(
                    conferenceYear,
                    conferenceLocation,
                    readableLocationName, [{ 
                        title: 'Sessions', 
                        url: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/sessions/index.html`
                    }]
                ),
                conference_id: conferenceId,
                permalink: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/sessions/index.html`
            },
        },
        speakers: {
            data: {
                title: `Meet the OpenSearchCon ${conferenceYear} Speakers`,
                primary_title: `Meet the OpenSearchCon ${conferenceYear} Speakers`,
                breadcrumbs: createBreadcrumbItemsOverride(
                    conferenceYear,
                    conferenceLocation,
                    readableLocationName, [{ 
                        title: 'Speakers', 
                        url: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/speakers/index.html`
                    }]
                ),
                conference_id: conferenceId,
                permalink: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/speakers/index.html`
            }
        },
        unconference: {
            data: {
                title: `OpenSearchCon ${conferenceYear} Session: Unconference`,
                primary_title: `OpenSearchCon ${conferenceYear} Session: Unconference`,
                breadcrumbs: createBreadcrumbItemsOverride(
                    conferenceYear,
                    conferenceLocation,
                    readableLocationName, [{ 
                        title: 'Unconference', 
                        url: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/Unconference/index.html`
                    }]
                ),
                conference_id: conferenceId,
                permalink: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/Unconference/index.html`,
            },
        },
        workshops: {
            data: {
                title: `OpenSearchCon ${conferenceYear} Workshops`,
                primary_title: `OpenSearchCon ${conferenceYear} Workshops`,
                breadcrumbs: createBreadcrumbItemsOverride(
                    conferenceYear,
                    conferenceLocation,
                    readableLocationName, [{ 
                        title: 'Workshops', 
                        url: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/Workshops/index.html`
                    }]
                ),
                conference_id: conferenceId,
                permalink: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/Workshops/index.html`,
            },
        },
    };
    return sectionPagesOverrides;
}

/**
 * Return an object used to override properties in the sample Front Matter and Markdown for the various
 * Jekyll Collections configured for OpenSearchCon content.
 * @param {string} conferenceId A string defining the conference ID.
 * @param {object[]} placeholderSpeakers An array of object defining the placeholder community members.
 * @param {string} conferenceYear A string defining the 4-digit year of the conference.
 * @param {string} conferenceLocation A string defining the URL friendly name of the conference location
 * @param {string} readableLocationName A string defining the labe/text friendly readable name of the conference location.
 * @returns {object}
 */
function createBoilerplateCollectionEntryOverrides(conferenceId, placeholderSpeakers, conferenceYear, conferenceLocation, readableLocationName) {
    const sectionCollectionOverrides = {
        exhibitors: {
            data: {
                conference_id: conferenceId,
                logo: '/assets/media/community/members/no-image-available.svg',
            },
        },
        sessions: {
            data: {
                primary_presenter: placeholderSpeakers[0].short_name,
                title: `OpenSearchCon ${conferenceYear} Session: Session Title`,
                primary_title: `OpenSearchCon ${conferenceYear} Session: Session Title`,
                breadcrumbs: createBreadcrumbItemsOverride(
                    conferenceYear,
                    conferenceLocation,
                    readableLocationName, [{ 
                        title: 'Sessions', 
                        url: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/sessions/index.html`
                    }, {
                        title: 'Placeholder Session',
                        url: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/sessions/placeholder-session.html`
                    }]
                ),
                permalink: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/sessions/placeholder-session.html`,
                conference_id: conferenceId,
                presenters: placeholderSpeakers.map(speaker => speaker.short_name),
            },
        },
        speakers: placeholderSpeakers.map(speaker => ({
            data: speaker,
        })),
        workshops: {
            data: {
                primary_presenter: placeholderSpeakers[1].short_name,
                title: `OpenSearchCon ${conferenceYear} Session: Session Title`,
                primary_title: `OpenSearchCon ${conferenceYear} Session: Session Title`,
                breadcrumbs: createBreadcrumbItemsOverride(
                    conferenceYear,
                    conferenceLocation,
                    readableLocationName, [{ 
                        title: 'Unconference', 
                        url: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/workshops/index.html`
                    }, {
                        title: 'Placeholder Workshop',
                        url: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/workshops/placeholder-workshop.html`
                    }]
                ),
                permalink: `/events/opensearchcon/${conferenceYear}/${conferenceLocation}/workshops/placeholder-workshop.html`,
                conference_id: conferenceId,
                presenters: [placeholderSpeakers[1].short_name],
            },
        },
    };
    return sectionCollectionOverrides;
}

/**
 * Automate the creation of boilerplate file system objects necessary for creating the content for a new OpenSearch Conference
 * for a specfied year, at a specified location, and with either the complete combintation of sections, or a specified subsection of sections,
 * depending upon the CLI arguments provided by the user.
 * As is normative throughout the existing OpenSearchCon content the `conference_id` value that links together all of the sessions,
 * exhibitors, workshops, unconference, and community member speakers for a specific conferenceis created by concatenated the year 
 * and the url-friendly form of the confernce's location name; eg '2024-europe', or '2024-north-america' for the year 2024, 
 * and the locations of Europe and North America respectively. 
 * 
 * Content for a conference requires the following to exist within the project-website repository:
 * 
 * * A file system structure for the conference landing page, and subdirectories for all of the conference sections.
 *   This content is defined within the 'events/opensearchcon'. For example for the year 2024, and the location of Europe
 *   the following file subdirectories will be created:
 *   
 * * events/opensearchcon/2024/europe -- Root directory for conference pages.
 * * events/opensearchcon/2024/europe/index.md -- Conference landing page.
 * * events/opensearchcon/2024/europe/exhibitors/index.md -- Conference exhibitors listing page.
 * * events/opensearchcon/2024/europe/sessions/index.md -- Conference sessions listing page.
 * * events/opensearchcon/2024/europe/speakers/index.md -- Conference speakers listing page.
 * * events/opensearchcon/2024/europe/unconference/index.md -- The special "Unconference" page (if desired).
 * * events/opensearchcon/2024/europe/workshops/index.md -- The conference workshops listing page (if desired).
 * 
 * Boilerplate Front Matter and Markdown content are copied for each new 'index.md' file from the corresponding 
 * '_sample-index.md' file that can be found within the confernce archive file system.
 * See the contents of the files within "events/opensearchcon/archive/_sample-year/_sample-year-location/..."
 * for details. The proprties and content defined within each sample file are overridden with values appropriate
 * for the specified year and location before being written to disk.
 * 
 * Placeholder content is created in the related Jekyll Collections as boilerplate reference points to get started
 * with adding / configuring-existing Community Members as speakers, sessions, workshops, and exhibitors. 
 * The output of this program will result in the following additions (assuming 2024, and europe):
 * 
 * * _opensearchcon_exhibitors/2024-europe-placeholder-exhibitor.md -- Boilerplate exhibitor collection entry.
 * * _opensearchcon_sessions/2024-europe-placeholder-session.md -- Boilerplate session collection entry.
 * * _opensearchcon_workshops/2024-europe-placeholder-workshop.md -- Boilerplate workshop collection entry.
 * * _community_members/placeholder-speaker-2024-europe-1.md -- Boilerplate Community Member collection entry configured as a keynote speaker for the 2024-europe conference.
 * * _community_members/placeholder-speaker-2024-europe-2.md -- Boilerplate Community Member collection entry configured to NOT be a keynote speaker for the 2024-europe conference.
 * 
 * The placeholder session is configured with the placeholder-speaker-2024-europe-1 community member as its primary presenter,
 * and with the other as an additional prsenter. The placeholder workshop is configured with the 'placeholder-speaker-2024-europe-2'
 * community member as its sole presenter.
 * 
 * The configuration data for the site's top header navigation menu will be augmented with a new menu item for
 * the new conference within the OpenSearchCon menu with sub menu items for each section. This means that executing
 * this script will result in changes to the `_data/top_nav.yml` file as appropriate.
 * 
 * It's worth noting that the serialization of JavaScript objects to YAML that update the `_data/top_nav.yml` file contents
 * do clean up the unnecessary line breaks that have been present up to this point. FYI.
 * 
 * @param {object} inputArgs An object containing the validated input arguments as returned by `getInputArgs`.
 * @param {string} baseDir A string defining the repository root or base directory from which to perform all file system actions.
 * @returns {Promise<string>}
 * @see {getInputArgs}
 * @see {getReadableLocationName}
 * @see {createPlaceholderSpeakersOverrides}
 * @see {createEventPagesPaths}
 * @see {createSectionCollectionsPaths}
 * @see {createBoilerplateSectionsPagesOverrides}
 * @see {writeEventPagesBoilerplate}
 * @see {createBoilerplateCollectionEntryOverrides}
 * @see {writeCollectionPagesBoilerplate}
 * @see {updateTopNavMenu}
 */
async function run(inputArgs, baseDir) {
    const {conferenceYear, conferenceLocation, conferenceSections } = inputArgs;
    const splitSections = conferenceSections.split(',');
    const conferenceId = `${conferenceYear}-${conferenceLocation}`;
    const readableLocationName = getReadableLocationName(conferenceLocation);
    const conferenceBaseDir = path.join(baseDir, 'events', 'opensearchcon', conferenceYear, conferenceLocation);
    const samplePagesBaseDir = path.join(baseDir, 'events', 'opensearchcon', 'archive', '_sample-year', '_sample-year-location');
    const pagesPaths = createEventPagesPaths(splitSections, conferenceBaseDir, samplePagesBaseDir);
    const collectionsPaths = createSectionCollectionsPaths(
        splitSections.filter(
            section => section !== 'unconference' // There is no collection for the unconference
        ), baseDir
    );
    const placeholderSpeakers = createPlaceholderSpeakersOverrides(conferenceId, conferenceYear, conferenceLocation, readableLocationName);
    const sectionPagesOverrides = createBoilerplateSectionsPagesOverrides(conferenceId, conferenceYear, conferenceLocation, readableLocationName, splitSections);
    const configuredPagesOverrides = ['landingPage', ...splitSections].reduce((carry, current) => {
        return {
            ...carry,
            [current]: sectionPagesOverrides[current],
        }
    }, {});
    await writeEventPagesBoilerplate(pagesPaths, configuredPagesOverrides);

    const sectionCollectionOverrides = createBoilerplateCollectionEntryOverrides(conferenceId, placeholderSpeakers, conferenceYear, conferenceLocation, readableLocationName);
    const configuredCollectionOverrides = splitSections.reduce((carry, current) => {
        if (!sectionCollectionOverrides.hasOwnProperty(current)) {
            return carry;
        }
        return {
            ...carry,
            [current]: sectionCollectionOverrides[current],
        };
    }, {});
    await writeCollectionPagesBoilerplate(collectionsPaths, configuredCollectionOverrides);
    await updateTopNavMenu(baseDir, conferenceYear, conferenceLocation, readableLocationName, splitSections);
    return 'done';
}

if (process.argv.length === 2) {
    exitWithUsage();
} else if (process.argv.length >= 4) {
    const validatedInputArgs = getInputArgs(process.argv);
    run(validatedInputArgs, __dirname).then(console.log).catch(console.error);
} else {
    exitWithUsage(`Incomplete input arguments`, 1);
}