Spots

PHP, markdown and no dependencies

I’ve been thinking about building a travel site called romantic-weekend.com, focused on romantic weekend destinations in Europe and the United States. The basic idea is deliberately simple: people search Google for things like “romantic weekend in Paris”, “romantic weekend in Rome”, “romantic getaway in Napa Valley” or “romantic weekend in France”, and they land directly on a highly focused destination page. The site would contain broader landing pages for regions and countries, such as Europe, France, Italy and the United States, alongside individual destination pages for places like Paris, Venice, New York and San Francisco. Because I expect most visitors to arrive through Google rather than navigate from the homepage, each destination page needs to work well on its own, while still belonging to a clear overall structure.

The more I thought about the technical side

The more I thought about the technical side of the project, the less interested I became in using a traditional CMS. Romantic-weekend.com is not meant to be a complicated application. It does not need user accounts, comments, dashboards, workflows, permissions or a complex database model. At its core, it is an editorial website made up of structured pages. That made me wonder whether the simplest possible architecture might also be the best one: PHP for the site engine, Markdown files for the content, the filesystem for the hierarchy and ordinary PHP templates for the output. I imagine the content directory looking something like this:

The nice thing about this structure is that

The nice thing about this structure is that the filesystem itself describes the site. A file at /content/europe/france/paris.md naturally becomes the page /europe/france/paris/, while /content/europe/france/index.md becomes /europe/france/. I don’t need a database table that says Paris belongs to France and France belongs to Europe, because the location of the file already tells me that. I also don’t need to repeat the URL, the parent page, the country and the region in every content file. PHP can derive most of that automatically from the path. A Paris page could then be very simple:

The Markdown file only describes the content. PHP

The Markdown file only describes the content. PHP handles everything around it: the URL, breadcrumbs, metadata, templates, related destinations, canonical URLs, sitemap entries and navigation. That separation is important to me because I want the content files to stay readable even if the site becomes quite large. If romantic-weekend.com eventually contains hundreds of destinations, I still want adding a new one to be as simple as creating a new Markdown file in the correct directory.

For example, adding Lyon should ideally mean creating

For example, adding Lyon should ideally mean creating /content/europe/france/lyon.md and nothing else. The France page should automatically discover it. The sitemap should automatically include it. The breadcrumb should automatically become “Europe › France › Lyon”. A “More romantic weekends in France” section should automatically be able to link to it. The system should understand the hierarchy without me having to maintain the same information in five different places.

That is also why I like the idea

That is also why I like the idea of country and region pages being proper content pages rather than just technical category archives. /europe/ could target searches around romantic weekend destinations in Europe. /europe/france/ could target romantic weekends in France. /usa/california/ could target romantic weekend getaways in California. These pages could contain their own editorial introductions, recommendations and internal links, while PHP automatically inserts the relevant child destinations. This gives the site a clear SEO structure without forcing visitors to navigate through every level before reaching the page they actually want.

My first instinct for handling Markdown was to

My first instinct for handling Markdown was to use a mature package such as league/commonmark. That would certainly work, and for many projects it would be the sensible choice. But romantic-weekend.com made me question whether I really need a complete Markdown implementation at all. I control every content file myself. There are no users pasting arbitrary Markdown into a form. I do not need to support every edge case in the CommonMark specification. In practice, the editorial content probably only needs headings, paragraphs, bold and italic text, links, lists, blockquotes and maybe images.

That means I could write a deliberately small

That means I could write a deliberately small Markdown parser instead of pulling in a dependency. The distinction matters: I would not be trying to write a standards-compliant Markdown parser. I would be defining a small markup format for this specific website that happens to use familiar Markdown syntax. If the site supports #, ##, **bold**, [links](...) and simple lists, that is the specification. Anything more complicated simply does not belong in the content format unless I consciously decide to add it later.

The same goes for the metadata block at

The same goes for the metadata block at the top of each file. I do not need a complete YAML parser just to read three or four simple values. A lightweight parser that reads key: value lines is probably enough. That keeps the project extremely portable. In the simplest version, the entire runtime dependency stack could be nothing more than PHP itself.

That idea appeals to me more than I

That idea appeals to me more than I expected. The Markdown files become the database. Git becomes the version history. The directory tree becomes the taxonomy. PHP becomes the rendering engine. If I move the site to another server, I copy the project and it works. There is no database dump to import, no CMS installation to upgrade and no long dependency tree that needs to be restored before the site can even render a page.

News

PHP, markdown and no dependencies

I’ve been thinking about building a travel site called romantic-weekend.com, focused on romantic weekend destinations in Europe and the United States.

@spots #dev
Source: Dev.to
See more like this