Skip to content

Commit 3792546

Browse files
judelljudell
authored
revise blog layout and content (#2228)
1 parent 5095bd2 commit 3792546

File tree

6 files changed

+93
-245
lines changed

6 files changed

+93
-245
lines changed

‎blog/public/blog/welcome-to-the-xmlui-blog.md‎

Lines changed: 36 additions & 193 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,4 @@
1-
In this inaugural post we'll explore the development of the blog engine we're using on this site. Our tagline is *Practical User Interfaces Built Simply* and creating this blog couldn't have been simpler. The whole site, of which the blog is now a part, is an XMLUI app built with components including [NavPanel](https://docs.xmlui.org/components/NavPanel), [NavLink](https://docs.xmlui.org/components/NavLink), [Pages](https://docs.xmlui.org/components/Pages), [Page](https://docs.xmlui.org/components/Page), and [Markdown](https://docs.xmlui.org/components/Markdown).
2-
3-
Let's see how it evolved.
1+
In this inaugural post we'll explore the development of the blog engine we're using on this site. Our tagline is *Practical User Interfaces Built Simply* and creating this blog couldn't have been simpler. It's an XMLUI app built with a handful of core components (including [NavPanel](https://docs.xmlui.org/components/NavPanel), [NavLink](https://docs.xmlui.org/components/NavLink), [Pages](https://docs.xmlui.org/components/Pages), [Page](https://docs.xmlui.org/components/Page), and [Markdown](https://docs.xmlui.org/components/Markdown)) and a couple of [user-defined components](https://docs.xmlui.org/user-defined-components).
42

53
## The simplest possible thing
64

@@ -50,7 +48,7 @@ We started with the simplest possible approach: post metadata and data as litera
5048

5149
You can use it right here or you can click the ![](/resources/pg-popout.svg) icon to open a playground where you can make live changes.
5250

53-
This is a pretty good start! We can write posts, arrange them in reverse chronological order, and hey, it's the essence of a blog. Since it's a blog about XMLUI the live playground is a nice bonus that any XMLUI app might put to good use. The user interfaces that you build with XMLUI will require some explaining, it's handy to explain with working examples as well as images, text, and video.
51+
This is a pretty good start! We can write posts, arrange them in reverse chronological order, and hey, it's the essence of a blog. The live playground is a nice bonus that any XMLUI app might put to good use. The user interfaces that you build with XMLUI will require some explaining, it's handy to explain with working examples as well as images, text, and video.
5452

5553
Let's unpack how this works, there isn't much to it. The `App` declared in `Main.xmlui` sets up navigation.
5654

@@ -66,9 +64,9 @@ Let's unpack how this works, there isn't much to it. The `App` declared in `Main
6664
</App>
6765
```
6866

69-
Each Page contains a [user-defined component](https://docs.xmlui.org/user-defined-components) called `BlogPage`. In the prototype, the `BlogPage` component receives page content as `$props.content`.
67+
Each Page contains a user-defined component called `BlogPage` that receives the properties `content`, `title`, `author`, and `date`.
7068

71-
```xmlui copy {4}
69+
```xmlui
7270
<Pages>
7371
<Page url="/newest-post">
7472
<BlogPage
@@ -80,21 +78,16 @@ Each Page contains a [user-defined component](https://docs.xmlui.org/user-define
8078
</Pages>
8179
```
8280

83-
Here's how the prototype `BlogPage` assembles data and metadata to create a post.
81+
Here's how `BlogPage` assembles data and metadata to create a post.
8482

85-
```xmlui copy {4, 6, 8, 11}
83+
```xmlui /$props/
8684
<Component name="BlogPage">
87-
<VStack width="85%">
88-
<VStack>
89-
<H1>{$props.title}</H1>
90-
<HStack gap="$space-2">
91-
<Text>{$props.date}</Text>
92-
<Text> - </Text>
93-
<Text>{$props.author}</Text>
94-
</HStack>
85+
<VStack gap="0">
86+
<H1>{$props.post.title}</H1>
87+
<Text>{$props.post.date} • {$props.post.author}</Text>
9588
</VStack>
96-
<Markdown content="{$props.content}" />
97-
</VStack>
89+
<Image src="/blog/images/{$props.post.image}" />
90+
<Markdown marginTop="$space-4" data="/blog/{$props.post.slug}.md" />
9891
</Component>
9992
```
10093

@@ -192,7 +185,7 @@ The `NavLink` uses the post's slug to bind to its corresponding `Page`.
192185
</Page>
193186
```
194187

195-
And the `Page` passes the complete post object to `BlogPage`. In v1 we used the `content` property of the `Markdown` component to pass a string. In v2 we use the `data` property to pass an URL constructed from the post slug.
188+
And the `Page` passes the complete post object to `BlogPage`. In v1 we used the `content` property of the `Markdown` component to pass a string. In v2 we use the `data` property to pass a URL constructed from the post slug.
196189

197190
```xmlui copy {11}
198191
<Component name="BlogPage">
@@ -216,31 +209,32 @@ Although it's feasible to use a `NavGroup` to list the posts, a blog should real
216209

217210
```xmlui copy
218211
<Component name="BlogOverview">
219-
<Stack width="85%">
220-
<H1>XMLUI Blog</H1>
221-
<Text>Latest updates, tutorials, and insights for building with XMLUI</Text>
222-
</Stack>
223-
<List
224-
data="{
212+
<CVStack>
213+
<VStack width="100%">
214+
<H1>XMLUI Blog</H1>
215+
<Text>Latest updates, tutorials, and insights for building with XMLUI</Text>
216+
<List data="{
225217
$props.posts.sort(function(a, b) {
226218
return new Date(b.date) - new Date(a.date);
227219
})
228220
}">
229-
<VStack gap="$space-2" width="90%">
230-
<Link to="/blog/{$item.slug}">
231-
<Text fontSize="larger">
232-
{$item.title}
233-
</Text>
234-
</Link>
235-
<Text>
236-
{$item.date} • {$item.author}
237-
</Text>
238-
<Link to="/blog/{$item.slug}">
239-
<Image src="/blog/images/{$item.image}" />
240-
</Link>
241-
<Stack height="3rem" />
221+
<VStack gap="$space-2">
222+
<Link to="/blog/{$item.slug}">
223+
<Text fontSize="larger">
224+
{$item.title}
225+
</Text>
226+
</Link>
227+
<Text>
228+
{$item.date} • {$item.author}
229+
</Text>
230+
<Link to="/blog/{$item.slug}">
231+
<Image src="/blog/images/{$item.image}" />
232+
</Link>
233+
<Stack height="$space-8" />
234+
</VStack>
235+
</List>
242236
</VStack>
243-
</List>
237+
</CVStack>
244238
</Component>
245239
```
246240

@@ -271,7 +265,8 @@ We can't call it a blog unless it provides an RSS feed. For that we've added a s
271265

272266
## Deploy standalone
273267

274-
Suppose you wanted to decouple the blog engine from the monorepo and use it standalone? Let's start with this footprint.
268+
Our blog lives in the XMLUI monorepo where it coordinates with the landing page and docs.
269+
But it can exist standalone, you only need a folder with a handful of files.
275270

276271

277272
```
@@ -303,168 +298,16 @@ Here's the `index.html`.
303298
<title>XMLUI blog test</title>
304299
<script src="xmlui/xmlui-0.10.8.js"></script>
305300
<script src="xmlui/xmlui-playground.js"></script>
306-
<script>
307-
</script>
308301
</head>
309302
<body>
310303
</body>
311304
</html>
312305
```
313306

314-
And here's `Main.xmlui`.
315-
316-
```xmlui copy
317-
<Fragment>
318-
<App
319-
layout="vertical-full-header"
320-
noScrollbarGutters="false"
321-
when="{!window.location.hash.includes('/playground')}"
322-
var.posts = `{[
323-
{
324-
title: "Welcome to the XMLUI blog!",
325-
slug: "welcome-to-the-xmlui-blog",
326-
author: "Jon Udell",
327-
date: "2025-09-01",
328-
image: "blog-scrabble.png"
329-
},
330-
{
331-
title: "Lorem Ipsum!",
332-
slug: "lorem-ipsum",
333-
author: "H. Rackham",
334-
date: "1914-06-03",
335-
image: "lorem-ipsum.png"
336-
}
337-
]}`
338-
>
339-
<AppHeader>
340-
<property name="logoTemplate">
341-
<Link to="https://xmlui.org/">
342-
<Logo height="$space-8" />
343-
</Link>
344-
</property>
345-
<SpaceFiller />
346-
<Search
347-
data="{appGlobals.plainTextContent}"
348-
when="{mediaSize.sizeIndex > 2}" />
349-
<ToneSwitch />
350-
</AppHeader>
351-
<NavPanel when="{ mediaSize.sizeIndex > 2 && (searchState.value.searchResults.length === 0 || !searchState.value.searchQuery)}">
352-
<Stack
353-
paddingHorizontal="$space-4"
354-
paddingBottom="$space-4"
355-
when="{mediaSize.sizeIndex <= 2}">
356-
<Search data="{appGlobals.plainTextContent}" />
357-
</Stack>
358-
<NavGroup label="Recent posts" to="/blog" >
359-
<NavLink label="Welcome to the XMLUI blog!" to="/blog/{posts[0].slug}" />
360-
<NavLink label="Loreum ipsum" to="/blog/{posts[1].slug}" />
361-
</NavGroup>
362-
</NavPanel>
363-
<Pages fallbackPath="/404">
364-
<Page url="/blog">
365-
<BlogOverview posts="{posts}" />
366-
</Page>
367-
<Page url="/blog/{posts[0].slug}">
368-
<BlogPage post="{posts[0]}" />
369-
</Page>
370-
<Page url="/blog/{posts[1].slug}">
371-
<BlogPage post="{posts[1]}" />
372-
</Page>
373-
<Page url="/404">
374-
<PageNotFound />
375-
</Page>
376-
</Pages>
377-
<Footer>
378-
<CHStack width="*">
379-
This site is an XMLUI™ app.
380-
<SpaceFiller />
381-
<Link
382-
to="https://github.com/xmlui-org/xmlui/tree/main/docs/src"
383-
target="_blank">
384-
<Button variant="ghost" icon="github" />
385-
</Link>
386-
</CHStack>
387-
</Footer>
388-
</App>
389-
<StandalonePlayground when="{window.location.hash.includes('/playground')}" />
390-
</Fragment>
391-
```
392-
393-
That's all we need to serve the blog. Note that we include `xmlui-playground.js`. The live playgrounds you can use here are provided by an extension, and a standalone app can use that extension in the same way our main site does. So when you serve the blog from a static webserver, the playground examples work the same way.
394-
395-
You can host the standalone blog on any static webserver. We'll do that, but first let's create a search mechanism that's decoupled from the monorepo's build and works entirely client-side. We'll create two user-defined components: `SearchPrep` and `BlogSearch`.
396-
397-
```xmlui copy
398-
<Page url="/search">
399-
<SearchPrep posts="{posts}" />
400-
<BlogSearch posts="{posts}" searchIndex="{window.getblogPosts()}" />
401-
</Page>
402-
```
403-
404-
Here is `SearchPrep`. It uses `DataSource` in a `List` to read posts, and calls global functions to process them.
405-
406-
```xmlui copy
407-
<Component name="SearchPrep" var.count="{0}">
408-
409-
<List when="{count <= $props.posts.length}" data="{$props.posts}">
410-
<DataSource
411-
url="/blog/{$item.slug}.md"
412-
onLoaded="(data) => {
413-
// Set indexing state on first load;
414-
if (window.blogIsIndexing === '') {
415-
window.setBlogIndexing();
416-
}
417-
418-
window.setBlogSearchEntry('/blog/' + $item.slug, $item.title + '\n' + data);
419-
console.log('Added to blogPosts:', '/blog/' + $item.slug);
420-
count++;
421-
422-
if (window.getBlogSearchCount() >= $props.posts.length) {
423-
window.stopBlogIndexing();
424-
console.log('Blog indexing complete!');
425-
426-
}
427-
}" />
428-
429-
</List>
430-
431-
</Component>
432-
```
433-
434-
Here is `BlogSearch`. It provides a reactive search box so as you type, another global function finds fragments in posts that match your current query.
435-
436-
```xmlui copy
437-
<Component name="BlogSearch">
438-
<VStack gap="$space-4">
439-
<TextBox
440-
id="searchQuery"
441-
placeholder="Search blog posts..."
442-
width="15rem"
443-
/>
444-
<List data="{
445-
window.searchBlogPosts($props.posts, $props.searchIndex, searchQuery.value)
446-
}">
447-
<VStack gap="$space-2">
448-
<Link to="/blog/{$item.post.slug}">
449-
<H2 value="{$item.post.title}" />
450-
</Link>
451-
<List data="{$item.matches}">
452-
<Card>
453-
<Text backgroundColor="$color-warn-100" value="{$item.context}" />
454-
</Card>
455-
</List>
456-
</VStack>
457-
</List>
458-
</VStack>
459-
</Component>
460-
```
461-
462-
With these ingredients in place, I dragged the folder containing the standalone app onto Netlify's drop target. Check it out!
307+
I dragged the folder containing the standalone app onto Netlify's drop target. Check it out!
463308

464309
[https://test-xmlui-blog.netlify.app/](https://test-xmlui-blog.netlify.app/)
465310

466-
The post you are reading here was deployed in a similar way.
467-
468311
## XMLUI for publishing
469312

470313
We get it, blog engines are a dime a dozen. We made this one because XMLUI was already a strong publishing system that we use for the [docs](https://docs.xmlui.org), [demo](https://demo.xmlui.org), and [landing page](https://xmlui.org). The `Markdown` component, with its support for playgrounds, works really well and it made sense to leverage that for our blog. We're not saying that you *should* build a blog engine with XMLUI but it's clearly something you *could* do. We think it's pretty easy to create a competent engine that makes life easy for authors and readers.

‎blog/src/Main.xmlui‎

Lines changed: 29 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,41 @@
11
<App
2-
layout="vertical-full-header"
3-
noScrollbarGutters="false"
4-
var.posts = `{[
2+
layout="vertical"
3+
var.showNavPanelThreshold="{6}"
4+
var.posts=`{[
55
{
66
title: "Welcome to the XMLUI blog!",
77
slug: "welcome-to-the-xmlui-blog",
88
author: "Jon Udell",
9-
date: "2025-09-10",
9+
date: "2025-10-20",
1010
image: "blog-scrabble.png"
1111
}
12-
]}`
13-
>
12+
]}`>
13+
<AppState
14+
id="navState"
15+
initialValue="{{
16+
showNavPanel: showNav(),
17+
showNavPanelThreshold: showNavPanelThreshold,
18+
posts: posts.length
19+
}}" />
1420
<AppHeader>
1521
<property name="logoTemplate">
16-
<Link to="https://xmlui.org/">
17-
<Logo height="$space-8" />
22+
<CHStack height="$space-6">
23+
<Logo />
24+
<Text variant="em">Tutorials, tips, best practices</Text>
25+
</CHStack>
26+
</property>
27+
<property name="profileMenuTemplate">
28+
<SpaceFiller />
29+
<Link when="{!['/', '/blog'].includes($pathname)}" to="/">
30+
<Button height="$space-6" padding="$space-2" label="All Posts" />
1831
</Link>
1932
</property>
20-
<SpaceFiller />
21-
<Search
22-
data="{appGlobals.plainTextContent}"
23-
when="{mediaSize.sizeIndex > 2}" />
24-
<ToneSwitch />
2533
</AppHeader>
26-
<NavPanel
27-
when="{!window.location.hash.includes('/404') || mediaSize.sizeIndex <= 2}">
28-
<Stack
29-
paddingHorizontal="$space-4"
30-
paddingBottom="$space-4"
31-
when="{mediaSize.sizeIndex <= 2}">
32-
<Search data="{appGlobals.plainTextContent}" />
33-
</Stack>
34-
<NavGroup label="Recent posts" to="/blog" >
35-
<NavLink label="Welcome to the XMLUI blog!" to="/blog/{posts[0].slug}" />
34+
<NavPanel>
35+
<NavGroup label="Recent posts" to="/blog">
36+
<NavLink
37+
label="Welcome to the XMLUI blog!"
38+
to="/blog/{posts[0].slug}" />
3639
</NavGroup>
3740
</NavPanel>
3841
<Pages fallbackPath="/404">
@@ -50,14 +53,10 @@
5053
</Page>
5154
</Pages>
5255
<Footer>
53-
<CHStack width="*">
56+
<CHStack width="100%">
5457
This site is an XMLUI™ app.
5558
<SpaceFiller />
56-
<Link
57-
to="https://github.com/xmlui-org/xmlui/tree/main/docs/src"
58-
target="_blank">
59-
<Button variant="ghost" icon="github" />
60-
</Link>
59+
<ToneSwitch />
6160
</CHStack>
6261
</Footer>
63-
</App>
62+
</App>

‎blog/src/Main.xmlui.xs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
function showNav() {
2+
return posts.length > showNavPanelThreshold && mediaSize.sizeIndex > 2;
3+
}

0 commit comments

Comments
 (0)