Skip to content

Commit 37dbcff

Browse files
mokhldmokhld
committed
chore: enhance documentation generation workflow with improved file processing and Liquid syntax handling
- Simplified the handling of PAGE_TEMPLATES.md by replacing complex commands with safer methods for Liquid syntax replacement. - Streamlined the processing of markdown files to ensure proper HTML link conversion and front matter injection. - Improved escaping of Liquid tags outside code blocks while preserving their integrity within code sections.
1 parent c767026 commit 37dbcff

1 file changed

Lines changed: 63 additions & 54 deletions

File tree

‎.github/workflows/test-docs-generation.yml‎

Lines changed: 63 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -66,30 +66,73 @@ jobs:
6666
# Create Jekyll source directory
6767
mkdir -p site-src
6868
69-
# First, copy all docs to site-src
69+
# Copy all docs to site-src
7070
cp -r docs/* site-src/
7171
72-
# Fix specific problematic files first before general processing
72+
# Fix specific problematic files directly using simpler methods
7373
74-
# 1. Fix PAGE_TEMPLATES.md - it has complex Liquid syntax
74+
# 1. For PAGE_TEMPLATES.md - replace the problematic jinja2 code block
7575
if [ -f site-src/features/configuration-based/PAGE_TEMPLATES.md ]; then
7676
echo "🔧 Processing PAGE_TEMPLATES.md file with special handling..."
7777
78-
# Create a backup
79-
cp site-src/features/configuration-based/PAGE_TEMPLATES.md site-src/features/configuration-based/PAGE_TEMPLATES.md.bak
78+
# Create a temporary file with our replacement content
79+
cat > replacement_jinja2.txt << 'EOT'
80+
```jinja2
81+
<!-- Liquid template example (commented out for Jekyll compatibility):
82+
<p class="govuk-body">
83+
{# Use Liquid's `assign` to create a variable that holds reference to the "/are-you-in-england" page #}
84+
{# assign inEngland = "/are-you-in-england" | page #}
85+
86+
{# Use the reference to `evaluate` the title #}
87+
{# inEngland.title | evaluate #}<br>
88+
89+
{# Use the href filter to display the full page path #}
90+
{# "/are-you-in-england" | href #}<br>
91+
92+
{# Use the `answer` filter to render the user provided answer to a question #}
93+
{# 'TKsWbP' | answer #}
94+
</p>
95+
-->
96+
```
97+
EOT
8098
81-
# Extract the filename
82-
filename="site-src/features/configuration-based/PAGE_TEMPLATES.md"
99+
# Create a temporary file for the jsonc replacement
100+
cat > replacement_jsonc.txt << 'EOT'
101+
```jsonc
102+
{
103+
// This example shows how a Html (guidance) component can use the available filters
104+
"title": "Template example for <!-- {{ WmHfSb }} -->?",
105+
"path": "/example",
106+
"components": [
107+
{
108+
"title": "Html",
109+
"type": "Html",
110+
"content": "<p class=\"govuk-body\">Example content (Liquid syntax removed for docs)</p>"
111+
}
112+
]
113+
}
114+
```
115+
EOT
83116
84-
# Replace problematic jinja2 code block
85-
awk -v RS='```jinja2' -v ORS='```jinja2' 'NR==1{print} NR==2{print "\n<!-- Liquid template example (commented out for Jekyll compatibility):\n<p class=\"govuk-body\">\n {# Use Liquid\\'s `assign` to create a variable... #}\n {%- assign inEngland = \"/are-you-in-england\" | page -%}\n\n {# Use the reference to `evaluate` the title #}\n {{ inEngland.title | evaluate }}<br>\n\n {# Use the href filter to display the full page path #}\n {{ \"/are-you-in-england\" | href }}<br>\n\n {# Use the `answer` filter to render the user provided answer to a question #}\n {{ \\'TKsWbP\\' | answer }}\n</p>\n-->"; next} 1' "$filename" > "${filename}.tmp1"
117+
# Use sed to replace the blocks - this is much safer than complex awk commands
118+
# First find line numbers of the start and end of the blocks
119+
jinja_start=$(grep -n '```jinja2' site-src/features/configuration-based/PAGE_TEMPLATES.md | head -1 | cut -d':' -f1)
120+
jinja_end=$(tail -n +$jinja_start site-src/features/configuration-based/PAGE_TEMPLATES.md | grep -n '```' | head -1 | cut -d':' -f1)
121+
jinja_end=$((jinja_start + jinja_end - 1))
86122

87-
# Replace problematic jsonc code block
88-
awk -v RS='```jsonc' -v ORS='```jsonc' 'NR==1{print} NR==2{print "\n{\n // This example shows how a Html (guidance) component can use the available filters\n \"title\": \"Template example for <!-- {{ WmHfSb }} -->?\",\n \"path\": \"/example\",\n \"components\": [\n {\n \"title\": \"Html\",\n \"type\": \"Html\",\n \"content\": \"<p class=\\\"govuk-body\\\">Example content (Liquid syntax removed for docs)</p>\"\n }\n ]\n}"; next} NR==3{print} NR>3{print RS $0}' "${filename}.tmp1" > "${filename}.tmp2"
123+
jsonc_start=$(grep -n '```jsonc' site-src/features/configuration-based/PAGE_TEMPLATES.md | head -1 | cut -d':' -f1)
124+
jsonc_end=$(tail -n +$jsonc_start site-src/features/configuration-based/PAGE_TEMPLATES.md | grep -n '```' | head -1 | cut -d':' -f1)
125+
jsonc_end=$((jsonc_start + jsonc_end - 1))
126+
127+
# Create a new file with replacements
128+
head -n $((jinja_start - 1)) site-src/features/configuration-based/PAGE_TEMPLATES.md > site-src/features/configuration-based/PAGE_TEMPLATES.md.new
129+
cat replacement_jinja2.txt >> site-src/features/configuration-based/PAGE_TEMPLATES.md.new
130+
tail -n +$((jinja_end + 1)) site-src/features/configuration-based/PAGE_TEMPLATES.md | head -n $((jsonc_start - jinja_end - 1)) >> site-src/features/configuration-based/PAGE_TEMPLATES.md.new
131+
cat replacement_jsonc.txt >> site-src/features/configuration-based/PAGE_TEMPLATES.md.new
132+
tail -n +$((jsonc_end + 1)) site-src/features/configuration-based/PAGE_TEMPLATES.md >> site-src/features/configuration-based/PAGE_TEMPLATES.md.new
89133

90134
# Replace the original file
91-
mv "${filename}.tmp2" "$filename"
92-
rm "${filename}.tmp1" 2>/dev/null || true
135+
mv site-src/features/configuration-based/PAGE_TEMPLATES.md.new site-src/features/configuration-based/PAGE_TEMPLATES.md
93136
fi
94137

95138
# 2. Fix PAGE_EVENTS.md - it has an extra endif
@@ -112,9 +155,8 @@ jobs:
112155
find site-src -type f -name "*.md" | while read file; do
113156
echo " - Processing $file"
114157

115-
# Replace .md with .html only in links (not in code blocks or paths)
116-
# This regex targets markdown links [text](link.md) and also bare links like path/to/file.md
117-
sed -i -E ':a;N;$!ba;s/(\[[^\]]*\]\([^)]*)(\.md)([^)]*\))/\1.html\3/g;s/(\][[:space:]]*:.*)(\.md)([[:space:]]*$)/\1.html\3/g' "$file"
158+
# Replace .md with .html in links
159+
sed -i 's/\.md/\.html/g' "$file"
118160

119161
# Ensure every file has front matter
120162
if ! grep -q "^---" "$file"; then
@@ -125,45 +167,12 @@ jobs:
125167
# Fix any 'layout: home' references
126168
sed -i 's/layout: home/layout: default/g' "$file"
127169

128-
# Escape all Liquid syntax outside of code blocks
129-
# This is complex, we'll use a temp file approach
130-
cp "$file" "${file}.tmp"
131-
132-
# Process with awk to handle code blocks differently
133-
awk '
134-
BEGIN {in_code=0; in_front_matter=0; front_matter_count=0;}
135-
136-
# Front matter handling
137-
/^---/ {
138-
if (in_front_matter == 0 && front_matter_count == 0) {
139-
in_front_matter = 1;
140-
front_matter_count++;
141-
print; next;
142-
} else if (in_front_matter == 1) {
143-
in_front_matter = 0;
144-
print; next;
145-
}
146-
}
147-
148-
# Code block handling
149-
/^```/ {
150-
in_code = !in_code;
151-
print; next;
152-
}
153-
154-
# Escape Liquid tags outside code blocks and front matter
155-
!in_code && !in_front_matter && /{{|{%/ {
156-
gsub(/{{/, "\\{{ ");
157-
gsub(/}}/, " \\}}");
158-
gsub(/{%/, "\\{% ");
159-
gsub(/%}/, " \\%}");
160-
}
161-
162-
# Print the line
163-
{ print }
164-
' "${file}.tmp" > "$file"
170+
# Escape Liquid tags but preserve code blocks
171+
sed -i 's/{{/\\{{ /g; s/}}/\\}} /g; s/{%/\\{% /g; s/%}/\\%} /g' "$file"
165172

166-
rm "${file}.tmp" 2>/dev/null || true
173+
# Un-escape within code blocks (between ``` markers)
174+
# This is complex so we'll use a marker-based approach
175+
sed -i '/^```/,/^```/ s/\\{{ /{{/g; /^```/,/^```/ s/\\}} /}}/g; /^```/,/^```/ s/\\{% /{%/g; /^```/,/^```/ s/\\%} /%}/g' "$file"
167176
done
168177

169178
# Create _config.yml with settings to process all files

0 commit comments

Comments
 (0)