Markdown Code Embed (Action)

Introduction
Adding Action To Your Repository
Quick Syntax Guide
- Embedding Files And Contents
- Embedding Process Output
More Info

Introduction

This repository provides the public action for the Markdown Code Embed script. Full documentation on using the script directly, with examples can be found there.

Some examples here are taken from there with less context, however I would recommend going over to the the main repository for full documentation on how to add code to your markdown files.

This is a lightweight means of embedding live code from your repository into your markdown documentation.

This action reports issues when it finds changes to your documentation, indicating that it may be out of date. These changes should at very least be checked to make sure that the documentation is correct, and be updated as part of the commit.

Adding Action To Your Repository

A quick example:

name: 'Update README files'

on:
  workflow_dispatch:
  pull_request:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      - name: Markdown Code Embed
        uses: ippie52/markdown_code_embed_action@latest
        with: 
          args: '-s'

The above is embedded using this script and reflects the contents of the file example. This is a fairly straight forward action, which runs a job on any pull request into the main branch.

The arguments provided by

with: 
  args: '-s'

are simply passed through to the mdce.py script, as shown below. Here, we're simply passing the --sub option to check through all sub-directories.

Usage of the mdce.py script:

usage: EmbedCode [-h] [-d directory [directory ...]]
                 [-f file_name [file_name ...]] [-e directory [directory ...]]
                 [-i] [-s] [-b] [-g] [-u] [-q]

Embed code within markdown documents

options:
  -h, --help            show this help message and exit
  -d directory [directory ...], --directories directory [directory ...]
                        Directories to be scanned for README.md files
  -f file_name [file_name ...], --files file_name [file_name ...]
                        Files to be scanned
  -e directory [directory ...], --exclude directory [directory ...]
                        Directories to exclude from searching
  -i, --include-self    Includes the directory (and sub-directories with -s)
                        of this script when parsing
  -s, --sub             Checks all sub-directories
  -b, --backup          Backs up the original file, appending ".old" to the
                        file name
  -g, --ignore-git      Exit value ignores changes in git
  -u, --ignore-untracked
                        Exit value ignores changes to untracked files
  -q, --quiet           Reduces the number of messages printed

Quick Syntax Guide

This guide is for the syntax within your markdown files.

Embedding Files And Contents

General rules:

The opening code block must all be on one line.
Must start with at least three back-ticks.
Must have a language/syntax type (here is a decent list).
Relative file name placed after the syntax, following a colon.
Line number range, if required, provided using the -s (--start) and -e (--end) options. A single line is provided by setting the start line only.
Must be a closing block with greater than or equal to the number of back-ticks in the opening block.

Syntax:

```language:path/to/file -s start_line -e end_line
```

Example:

``` python:mdce.py -s 2 -e 6
```

Embedding Process Output

Additional rules for process captures:

General rules above must be met
Option -r appear in the options list.
Arguments, if required, must be provided after the -a option as follows:
- Single arguments must be in two different sets of quotation marks, e.g. "'argument'", to prevent the outermost quotation marks being stripped.
- Multiple arguments must appear in quotation marks, but additional (different) quotations marks are only required to preserve white space, e.g. "arg1 'arg 2' arg3".
Line numbers, if set, will be ignored
Only data sent to stdout will be recorded. For stderr, pipe the output via an argument or wrapper script.

Examples:

```language:path/to/file -r -a "arg1 arg2 'arg 3'"
```

```text:/usr/bin/ls -r -a "'.'"
```

More Info

For more information, please head over to the main repository

ippie52 / markdown_code_embed_action