Skip to content

Commit 1dd4a1f

Browse files
mokhldmokhld
committed
chore: refine documentation generation workflow with enhanced Liquid syntax handling and markdown processing
- Improved the handling of PAGE_TEMPLATES.md by implementing safer methods for Liquid syntax replacement and creating backups before modifications. - Enhanced markdown file processing to ensure proper conversion of links from .md to .html while preserving code blocks and front matter. - Streamlined the escaping of Liquid tags outside code blocks, ensuring integrity during documentation generation.
1 parent 37dbcff commit 1dd4a1f

1 file changed

Lines changed: 54 additions & 63 deletions

File tree

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

Lines changed: 54 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -66,73 +66,30 @@ jobs:
6666
# Create Jekyll source directory
6767
mkdir -p site-src
6868
69-
# Copy all docs to site-src
69+
# First, copy all docs to site-src
7070
cp -r docs/* site-src/
7171
72-
# Fix specific problematic files directly using simpler methods
72+
# Fix specific problematic files first before general processing
7373
74-
# 1. For PAGE_TEMPLATES.md - replace the problematic jinja2 code block
74+
# 1. Fix PAGE_TEMPLATES.md - it has complex Liquid syntax
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 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
78+
# Create a backup
79+
cp site-src/features/configuration-based/PAGE_TEMPLATES.md site-src/features/configuration-based/PAGE_TEMPLATES.md.bak
9880
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
81+
# Extract the filename
82+
filename="site-src/features/configuration-based/PAGE_TEMPLATES.md"
11683
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))
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"
12286
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
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"
13389
13490
# Replace the original file
135-
mv site-src/features/configuration-based/PAGE_TEMPLATES.md.new site-src/features/configuration-based/PAGE_TEMPLATES.md
91+
mv "${filename}.tmp2" "$filename"
92+
rm "${filename}.tmp1" 2>/dev/null || true
13693
fi
13794
13895
# 2. Fix PAGE_EVENTS.md - it has an extra endif
@@ -155,8 +112,9 @@ EOT
155112
find site-src -type f -name "*.md" | while read file; do
156113
echo " - Processing $file"
157114
158-
# Replace .md with .html in links
159-
sed -i 's/\.md/\.html/g' "$file"
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"
160118
161119
# Ensure every file has front matter
162120
if ! grep -q "^---" "$file"; then
@@ -167,12 +125,45 @@ EOT
167125
# Fix any 'layout: home' references
168126
sed -i 's/layout: home/layout: default/g' "$file"
169127
170-
# Escape Liquid tags but preserve code blocks
171-
sed -i 's/{{/\\{{ /g; s/}}/\\}} /g; s/{%/\\{% /g; s/%}/\\%} /g' "$file"
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"
172165
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"
166+
rm "${file}.tmp" 2>/dev/null || true
176167
done
177168
178169
# Create _config.yml with settings to process all files

0 commit comments

Comments
 (0)