md_to_conf

expand_file_globs(patterns, exclude_patterns=None)

Expand a list of file path patterns into a de-duplicated, ordered list of absolute paths, then remove any paths that match an exclusion pattern.

Include patterns

• Standard file paths or shell globs (docs/*.md, **/*.md).
• A pattern prefixed with ! is treated as an exclusion instead of an include, e.g. !docs/draft.md or !drafts/**.

Exclusion patterns (applied last, highest precedence): - Passed via the exclude_patterns argument (populated from the --exclude CLI flag). - Also accepted inline as !-prefixed entries in patterns.

Patterns that match no files are treated as literal paths (so the missing-file error is reported by validate_args for include patterns; non-matching exclude patterns are silently ignored).

Source code in md_to_conf/__init__.py

def expand_file_globs(patterns, exclude_patterns=None):
    """
    Expand a list of file path patterns into a de-duplicated, ordered list
    of absolute paths, then remove any paths that match an exclusion pattern.

    Include patterns:
      - Standard file paths or shell globs (``docs/*.md``, ``**/*.md``).
      - A pattern prefixed with ``!`` is treated as an exclusion instead of
        an include, e.g. ``!docs/draft.md`` or ``!drafts/**``.

    Exclusion patterns (applied last, highest precedence):
      - Passed via the ``exclude_patterns`` argument (populated from the
        ``--exclude`` CLI flag).
      - Also accepted inline as ``!``-prefixed entries in *patterns*.

    Patterns that match no files are treated as literal paths (so the
    missing-file error is reported by validate_args for include patterns;
    non-matching exclude patterns are silently ignored).
    """
    include = [p for p in patterns if not p.startswith("!")]
    inline_excludes = [p[1:] for p in patterns if p.startswith("!")]
    all_excludes = list(inline_excludes) + list(exclude_patterns or [])

    # Build the excluded set
    excluded = set()
    for pattern in all_excludes:
        matches = glob.glob(pattern, recursive=True)
        if matches:
            for path in matches:
                excluded.add(os.path.abspath(path))
        else:
            # Treat as a literal path
            excluded.add(os.path.abspath(pattern))

    expanded = _expand_include_patterns(include)
    return [p for p in expanded if p not in excluded]

main()

Main program

Source code in md_to_conf/__init__.py

def main():
    """
    Main program

    """
    logging.basicConfig(
        level=logging.INFO,
        format="%(asctime)s - \
        %(levelname)s - %(funcName)s [%(lineno)d] - \
        \t%(message)s",
    )
    LOGGER = logging.getLogger(__name__)

    # ArgumentParser to parse arguments and options
    PARSER = get_parser()

    ARGS = PARSER.parse_args()

    # Assign global variables
    try:
        # Set log level — --verbose overrides --loglevel.
        # The root logger level must be lowered so that DEBUG messages from
        # all sub-modules (client, converter, …) are not silently dropped
        # before they reach any handler.
        if ARGS.verbose:
            log_level = logging.DEBUG
        else:
            log_level = getattr(logging, ARGS.loglevel.upper(), logging.INFO)
        logging.getLogger().setLevel(log_level)
        LOGGER.setLevel(log_level)

        MARKDOWN_FILES = expand_file_globs(ARGS.markdownFile, ARGS.exclude_patterns)
        SPACE_KEY = ARGS.spacekey
        USERNAME = os.getenv("CONFLUENCE_USERNAME", ARGS.username)
        API_KEY = os.getenv("CONFLUENCE_API_KEY", ARGS.apikey)
        ORGNAME = os.getenv("CONFLUENCE_ORGNAME", ARGS.orgname)
        ANCESTOR = ARGS.ancestor
        NOSSL = ARGS.nossl
        DELETE = ARGS.delete
        SIMULATE = ARGS.simulate
        VERSION = ARGS.version
        MARKDOWN_SOURCE = ARGS.markdownsrc
        LABELS = ARGS.labels
        PROPERTIES = dict(ARGS.properties)
        ATTACHMENTS = ARGS.attachment
        CONTENTS = ARGS.contents
        TITLE = ARGS.title
        REMOVE_EMOJIES = ARGS.remove_emojies
        RENDER_MERMAID = ARGS.render_mermaid

        validate_args(USERNAME, API_KEY, MARKDOWN_FILES, ORGNAME)

    except Exception as err:
        LOGGER.error("\n\nException caught:\n%s ", err)
        LOGGER.error("\nFailed to process command line arguments. Exiting.")
        sys.exit(1)

    LOGGER.info("\t----------------------------------")
    LOGGER.info("\tMarkdown to Confluence Upload Tool")
    LOGGER.info("\t----------------------------------")
    LOGGER.info("Files to process:\t%d", len(MARKDOWN_FILES))
    LOGGER.info("Space Key:\t%s", SPACE_KEY)
    if ANCESTOR:
        LOGGER.info("Ancestor:\t%s", ANCESTOR)
    LOGGER.debug("Org/URL:\t%s", ORGNAME)
    LOGGER.debug("Username:\t%s", USERNAME)
    if ARGS.verbose:
        LOGGER.debug("Verbose logging is enabled (DEBUG level).")

    multi_file = len(MARKDOWN_FILES) > 1

    # ── Build ConfluenceConverter instances (one per file) ─────────────────
    converters = []
    for md_file in MARKDOWN_FILES:
        LOGGER.info("Processing:\t%s", md_file)
        cc = ConfluenceConverter(
            md_file,
            MARKDOWN_SOURCE,
            TITLE,
            ORGNAME,
            not NOSSL,
            USERNAME,
            SPACE_KEY,
            API_KEY,
            ANCESTOR,
            VERSION,
        )
        converters.append((md_file, cc))

    # ── Pass 1: publish all pages, collect page_map ──────────────────────
    # When multi_file is True we run a first pass without cross-file link
    # resolution so that ALL page IDs are known before the second pass.
    page_map: dict = {}  # abs_path → {"page_id": int, "title": str, "url": str}

    for md_file, cc in converters:
        LOGGER.info("Pass 1 — publishing:\t%s", md_file)
        result = cc.convert(
            SIMULATE,
            DELETE,
            REMOVE_EMOJIES,
            CONTENTS,
            LABELS,
            PROPERTIES,
            ATTACHMENTS,
            render_mermaid=RENDER_MERMAID,
            page_map=None,  # no cross-file resolution yet
        )
        if result is not None:
            page_map[os.path.abspath(md_file)] = result

    # ── Pass 2 (multi-file only): re-update pages with cross-file links ───
    if multi_file and page_map and not SIMULATE and not DELETE:
        LOGGER.info(
            "Pass 2 — resolving cross-file links across %d pages …",
            len(page_map),
        )
        for md_file, cc in converters:
            LOGGER.info("Pass 2 — updating:\t%s", md_file)
            cc.convert(
                SIMULATE,
                DELETE,
                REMOVE_EMOJIES,
                CONTENTS,
                LABELS,
                PROPERTIES,
                ATTACHMENTS,
                render_mermaid=RENDER_MERMAID,
                page_map=page_map,
            )