Themes ​
A theme decides how the public site looks. NewsLoop ships three:
| Theme | Look |
|---|---|
| Classic | A busy news portal with a picture mosaic of top stories, coloured section blocks with a sidebar, a video strip and a dark footer. Every other theme builds on it. |
| Magazine | A compact header, a big hero story and large pictures. |
| Minimal | One column and words first. Suits newsletters and columnists. |
You switch themes under Site → Themes and adjust them under Site → Customise. You don't need to edit any files for that. This guide is for changing a theme's files or making your own.
Editing themes needs no build tools ​
Themes are plain Blade templates, CSS and JavaScript. Edit a file and upload it. You don't need Node or a build step.

After you edit theme files on a live site, click Refresh theme files on the Themes screen, or run this:
php artisan newsloop:themes:publish
This copies the theme's assets folder to public/themes, where browsers can load it. With APP_DEBUG=true the site notices changes by itself.
Make your own theme ​
The safest way is a child theme. It changes only what you want, and it keeps getting fixes when Classic is updated.
-
Create the folder
themes/my-paper. Use lowercase letters, numbers and dashes only. -
Add
themes/my-paper/theme.json:json{ "name": "My Paper", "version": "1.0.0", "author": "Your name", "description": "Our newspaper's look.", "parent": "classic", "styles": ["assets/my-paper.css"] } -
Add
themes/my-paper/assets/my-paper.csswith your changes. Classic's stylesheet loads first, so you only write the differences. -
Choose My Paper under Site → Themes.
To change a template, copy it from themes/classic/views to the same place under themes/my-paper/views, then edit the copy. Everything you don't copy still comes from Classic.
Folder layout ​
themes/my-paper/
theme.json the manifest (required)
screenshot.jpg shown on the Themes screen, 1280×800
assets/ CSS, JavaScript, fonts and images, copied to public/themes/my-paper
views/ Blade templates
lang/ optional JSON translations, such as lang/fr.json
theme.json ​
| Key | What it does |
|---|---|
name |
Required. Shown on the Themes screen. |
version |
Change it when you release an update, so the site refreshes the copied files. |
parent |
The folder name of the theme to build on. |
styles, scripts |
Files in the theme folder to load on every page. A parent's files load first. |
menus |
Menu locations the theme shows, as location: label. The built-in locations are header, top, footer and footer-legal. |
areas |
Places where the admin arranges blocks under Site → Layout. See below. |
settings |
Options for Site → Customise. See below. |
supports |
Informational flags, such as dark-mode and rtl. |
Layout areas ​
"areas": {
"home": {
"label": "Home page",
"kind": "sections",
"defaults": [
{ "type": "featured", "settings": { "layout": "hero", "count": 4 } },
{ "type": "latest", "settings": { "title": "Latest", "count": 8 } }
]
},
"sidebar": { "label": "Sidebar", "kind": "widgets", "defaults": [{ "type": "popular" }] }
}
kindissectionsfor full-width page parts andwidgetsfor sidebars and footers. Each block type allows one or both.defaultsis the layout a site uses until the admin saves their own.- Show an area in a template with
{{ $site->area('sidebar') }}.
Block types are featured, latest, category, sections, popular, picks, live, videos, gallery, series, tags, categories, social, ad, newsletter, text, banner and html.
A main column and a sidebar ​
Add "columns": true to a sections area to let each block choose where it sits. The admin picks Full width, Main column or Sidebar beside it under Site → Layout. The setting is stored as _column, and in defaults you set it the same way:
{ "type": "category", "settings": { "position": 1, "_column": "main" } },
{ "type": "social", "settings": { "style": "counter", "_column": "side" } },
{ "type": "sections", "settings": { "position": 3, "_column": "full" } }
Blocks in the main column and the sidebar that follow each other share a row:
<div class="nf-row">
<div class="nf-row__main">…</div>
<aside class="nf-row__side">…</aside>
</div>
A full-width block ends the row. A row with nothing in the sidebar gets nf-row--no-side. Block templates receive $column (full, main or side).
Sections by number ​
category and sections blocks can leave the section empty and use position, meaning "the Nth main section" in the order of Organise → Categories. A theme's default home page can then show real sections on any site without knowing their IDs. Section blocks pass the section's colour to their heading as --nf-section-color. A section without a colour uses the accent colour.
Layouts ​
| Block | Layouts |
|---|---|
featured |
hero, grid, mosaic (two big stories above three smaller ones) |
latest, category, picks |
grid, list, compact, lead, rows, overlay |
popular |
numbered, thumbs (numbered, with pictures), slider |
videos |
style: dark or light |
social |
style: links (icons) or counter (coloured tiles with follower counts) |
categories |
counts: show the number of articles in each section |
Classic's theme.js adds arrow buttons to sliders and rotates the header ticker. Without it, sliders still scroll by swiping, and the ticker shows its first headline.
Customizer settings ​
{ "key": "accent_color", "section": "Colours", "type": "color", "label": "Accent colour",
"default": "#c8102e", "css_var": "--nf-accent" }
| Type | Stored as | Reaches the page as |
|---|---|---|
color |
#rrggbb |
The CSS variable named in css_var |
number |
A number between min and max |
The CSS variable, plus unit such as px |
select |
One of the options keys |
data-nf-{key}="value" on <html> |
boolean |
On or off | data-nf-{key}="on" or "off" on <html> |
text, textarea, media |
Text, or a media library ID | $site->option('key') in templates |
Add "scope": "dark" to a colour to use it only in dark mode.
Every value is validated before it is saved. A colour can only be a hex code, so a setting can never inject CSS.
Templates ​
The site looks for templates in your theme, then its parent, then the core. The first one found wins.
| Page | Template, most specific first |
|---|---|
| Home | home |
| Section | category-{slug}, then category |
| Article | article-{type} (live, video, audio, gallery), then article |
| Page | page-{layout} (full-width, contact), then page |
| Tag, author, series, search | tag, author, series, search |
| Not found | 404 (410 for removed pages) |
| A block | blocks/{type} |
Every layout must include the core head and foot inside <head> and before </body>:
<head>@include('nf::head')</head>
...
@include('nf::foot')
The head prints the title, SEO and social tags, structured data, hreflang, stylesheets and customizer colours. The foot prints scripts, the cookie banner and the view counter.
What templates receive ​
Every template gets $site and $seo. Page templates also get their own data: $post, $page, $category, $posts (paginated), $tag, $author, $series, and $query with $results.
Commonly used $site methods:
| Method | Returns |
|---|---|
name(), tagline(), logo() |
Site details from System → Site settings → General |
menu('header') |
Links, each with label, url, new_tab and children |
url($post) |
An article's address |
section($post) |
The article's section: name, url and color |
image($media, 'card', eager: false) |
A responsive <img> with srcset. Presets are thumb, card, lead and full. |
date($time), time($time), ago($time) |
Dates in the site's timezone and language |
option('key') |
A customizer value |
area('sidebar') |
The blocks arranged in an area |
breaking() |
Breaking news from the last two days |
languages(), locale(), dir() |
Language details. dir() is ltr or rtl. |
Reusable pieces live in resources/views/public/partials: card, byline, share, comments, live-updates, pagination, breadcrumbs, language-switcher, paywall and contact-form. Include them with @include('theme::partials.card', ['post' => $post, 'variant' => 'grid']). To change one, copy it to your theme's views/partials folder.
Styles ​
The core stylesheet styles article content, comments, live blogs, forms and sharing. It reads these variables, which your theme can set:
:root {
--nf-accent: #c8102e; /* links and buttons */
--nf-accent-contrast: #fff; /* text on the accent colour */
--nf-bg: #fff;
--nf-surface: #f5f5f3; /* panels and boxes */
--nf-text: #151515;
--nf-muted: #5a5a5a;
--nf-border: #e2e2de;
--nf-radius: 4px;
--nf-font-body: system-ui, sans-serif;
--nf-font-heading: Georgia, serif;
--nf-article-size: 18px;
}
:root[data-nf-scheme="dark"] { /* the same variables for dark mode */ }
Use logical properties such as margin-inline-start instead of margin-left. Then Arabic, Hebrew and Urdu sites work without extra CSS.
Interactive features ​
The core script adds behaviour to plain markup, so themes need no JavaScript of their own:
| Attribute | Feature |
|---|---|
data-nf-toggle="element-id" |
Opens and closes a menu or panel. Escape closes it. |
data-nf-scheme-toggle |
Switches light and dark mode |
data-nf-progress |
A reading progress bar |
data-nf-share, data-nf-copy="url" |
The phone's share sheet, and copying a link |
Comments, live blog updates, the contact form, the view counter and cookie consent work automatically when you use the core partials.
Rules for theme authors ​
- Never print anything personal on a public page. Pages are cached and served to every visitor. That includes the visitor's name, a CSRF token or "Hello, Sam". Forms get what they need from the core script. The admin bar only shows on pages served live to signed-in staff.
- Escape everything. Use
{{ }}. Use{!! !!}only for content NewsLoop has already cleaned, such as$post->content_html. - Keep one
<h1>per page, labelled landmarks and visible focus. The built-in themes pass automated accessibility checks. Keep yours that way. - Don't load fonts or scripts from other companies without consent. Visitors' privacy law in the EU and UK applies to theme files too.
Checking a theme ​
- Open Site → Themes. Themes with a broken
theme.jsonare listed there with the reason. - Try the theme in Site → Customise before readers see it. The preview shows any theme without switching to it.
- Check pages in light and dark mode, at phone width, and in a right-to-left language.