- Astro-Powered: Utilize a modern static-site generation framework.
- Tailwind CSS: Enjoy rapid UI development with a utility-first CSS framework.
- Preline UI: Implement prebuilt UI components for added elegance.
- GSAP Integration: Impress with professional and polished animations.
- Markdown Content Collections: Organize and manage our content seamlessly.
- Starlight Documentation: A sleek, user-friendly, full-featured documentation theme.
- Internationalization (i18n): Integrates Astro’s internationalization features.
- SEO and Responsiveness: Ensure our site is discoverable and accessible on any device.
Start by installing the project dependencies. Open our terminal, navigate to the project's root directory, and execute:
npm installThis command will install all the necessary dependencies defined in the
package.json file.
With dependencies installed, you can utilize the following npm scripts to manage our project's development lifecycle:
npm run astro sync: Make sure all the content collection types are sync'dnpm run dev: Starts a local development server with hot reloading enabled.npm run preview: Serves our build output locally for preview before deployment.npm run build: Bundles our site into static files for production.
For detailed help with Astro CLI commands, visit Astro's documentation.
Before deployment, you need to create a production build:
npm run buildThis creates a dist/ directory with our built site (configurable via
outDir in Astro).
lib/ # surveilr Patterns code
src/ # Astro site code
├── assets/
│ ├── images/
│ | ├── content/ # Images for content collections (match structure exactly)
│ | | ├── docs/ # e.g. if src/content/docs has subdirectories, so will this
│ | | ├── insights/
│ | | ├── patterns/
│ | | └── (...) # all other content collections
| | └── (..static) # Static image assets for use across the site
│ ├── scripts/ # JS scripts
│ └── styles/ # CSS styles
├── components/ # Reusable components
│ ├── Meta.astro # Meta component for SEO
│ ├── sections/ # Components for various sections of the website
│ ├── ThemeIcon.astro # Component for toggling light/dark themes
│ └── ui/ # UI components categorized by functionality
├── content/ # Markdown files for blog posts, insights, patterns, and site configuration
│ ├── blog/
│ ├── docs/
│ ├── insights/
│ ├── patterns/
│ └── config.ts # Contains site-wide configuration options
├── data_files/ # Strings stored as JSON files
├── layouts/ # Components defining layout templates
│ └── MainLayout.astro # The main wrapping layout for all pages
├── pages/ # Astro files representing individual pages and website sections
│ ├── 404.astro # Custom 404 page
│ ├── blog/
│ ├── fr/ # Localized content
│ ├── contact.astro
│ ├── index.astro # The landing/home page
│ ├── insights/ # TODO: need to make this singular
│ ├── pattern/
│ ├── robots.txt.ts # Dynamically generates robots.txt
│ └── services.astro
└── utils/ # Shared utility functions and helpersStatic files served directly to the browser are within the public directory at
the root of the project.
public/ └── banner-pattern.svgSome components have properties defined as TypeScript variables within the
component file. Here's an example of customizing the FeaturesGeneral
component:
// Define the string variables title and subTitle for the main heading and sub-heading text.
const title: string = "Meeting Industry Demands";
const subTitle: string =
"At `surveilr`, we tackle the unique challenges encountered in the cybersecurity and compliance sectors.";For collections of content like testimonials or statistics, edit the corresponding array of objects:
// An array of testimonials
const testimonials: Testimonial[] = [...];
// An array of statistics
const statistics: StatProps[] = [...];Modify the content within these arrays to reflect our data.
You can pass values to props directly in the page files for components used
across pages. Here's an example of a HeroSection and ClientsSection
component with inline props:
<HeroSection
subTitle="Top-quality hardware tools and expert construction services for every project need."
primaryBtn="Start Exploring"
primaryBtnURL="/explore"
/>
<ClientsSection
title="Trusted by Industry Leaders"
subTitle="Experience the reliability chosen by industry giants."
/>Edit the props such as title, subTitle, primaryBtn, etc., to personalize
these sections. Ensure that you maintain the structure and data types of the
props.
Edit the navigation.ts file within the utils directory to manage navigation
bar and footer links:
Edit the navBarLinks array to adjust navigation bar links:
// An array of links for the navigation bar
export const navBarLinks: NavLink[] = [
{ name: "Home", url: "/" },
{ name: "Patterns", url: "/patterns" },
{ name: "Services", url: "/services" },
{ name: "Blog", url: "/blog" },
{ name: "Contact", url: "/contact" },
];Replace name with the display text and url with the appropriate path to
pages on our site.
Similarly, adjust the links displayed in the footer by editing the footerLinks
array:
// An array of links for the footer
export const footerLinks: FooterLinkSection[] = [
{
section: "Product",
links: [
{ name: "Tools & Equipment", url: "/tools-equipment" },
{ name: "Construction Services", url: "/construction-services" },
{ name: "Pricing", url: "/pricing" },
],
},
{
section: "Company",
links: [
{ name: "About us", url: "/about" },
{ name: "Blog", url: "/blog" },
{ name: "Careers", url: "/careers" },
{ name: "Customers", url: "/customers" },
],
},
];Each section within the footerLinks array represents a group of links. Update
the section value for the group heading and modify each link's name and
url as needed.
Replace the placeholder URLs in the socialLinks object with our social media
profiles:
// An object of links for social icons
export const socialLinks: SocialLinks = {
facebook: "#",
twitter: "#",
github: "#",
linkedin: "#",
instagram: "#",
};Note
Remember to add complete and valid URLs for the navigation to function properly. These customizations will reflect throughout our Astro site, promoting consistency across all pages.
We also have Navbar.astro and NavbarMegaMenu.astro components located in
src/components/sections/navbar&footer. Ensure to update these components if
additional customization or specific configurations are required for the
navigation bar or mega menu.
Key Features:
- Site Navigation and Search: Navigate through the documentation with ease using intuitive sidebar and built-in search functionality.
- Internationalization: Cater to a global audience with the ability to switch languages, making documentation accessible to everyone, everywhere.
- SEO Friendly: Optimized for search engines to help users quickly find the information they need.
- Code Highlighting and Dark Mode: Enhances code readability with syntax highlighting, and offers a dark mode to reduce eye strain for users.
- Mobile Responsive Design: Whether you're on a phone, tablet, or desktop, the documentation adapts to our screen size for optimal readability.
With Starlight, you gain access to a wealth of powerful features and integrations, along with extensive customization options to fit our needs.
Note
Dive into the Starlight's comprehensive feature list and learn how it can streamline our development process by visiting the theme's documentation site.
Experience buttery smooth scrolling with Lenis. We've integrated Lenis to provide an enhanced scrolling experience that's both fluid and responsive.
Here's how we set up Lenis in src/assets/scripts/lenisSmoothScroll.js:
// src/assets/scripts/lenisSmoothScroll.js
import "@styles/lenis.css";
import Lenis from "lenis";
const lenis = new Lenis();
function raf(time) {
lenis.raf(time);
requestAnimationFrame(raf);
}
requestAnimationFrame(raf);And then add it to MainLayout.astro:
<script>
import "@scripts/lenisSmoothScroll.js";
</script>Please note that smooth scrolling can affect accessibility and performance on some devices, so be sure to test it comprehensively across different environments.
Note
If you would like to remove Lenis and return to the browser's default
scrolling behavior, simply comment out or delete these lines from the
MainLayout.astro file and /starlight/Head.astro if you are using Docs.
For individual pattern pages, GSAP has been integrated to
add engaging animations that execute as soon as the pattern page loads. You can
find and modify the GSAP configuration in the script sections of the pattern
page file located at src/pages/pattern/[...slug].astro and the insights page
at src/pages/insights/[...slug].astro:
<script>
import { gsap } from "gsap";
// Initialize GSAP animations...
</script>Customizing Animations:
Please tailor the GSAP animations within this script to fit our project's look and feel. The provided example is a starting point, representing how to leverage GSAP for immediate visual impact as a pattern page loads.
Modifying or Removing Animations:
- To modify an animation, update the properties and parameters within the
gsap.from()method, or add new GSAP animation calls as required. - Should GSAP not be needed, or if you prefer a different animation method, simply remove the aforementioned script segment.
Note
We've chosen to keep the integration lean and focused, but GSAP's comprehensive documentation can be referred to for more complex animations: GSAP Documentation.
To achieve a cleaner and more spacious design, the default scrollbar has been visually removed. While this choice fits the aesthetic goals of the project, it's important to consider that hiding scrollbars can sometimes affect accessibility and user experience. We recommend evaluating this design decision within the context of our user base and their needs.
For those who prefer custom-styled scrollbars, we suggest using the tailwind-scrollbar plugin, which adds Tailwind CSS utilities for scrollbar styles, allowing for more controlled customization that can also meet accessibility standards.
Note
If you wish to return the default scrollbar, you can comment out or remove the
following CSS from src/layouts/MainLayout.astro:
<style>
.scrollbar-hide::-webkit-scrollbar {
display: none;
}
.scrollbar-hide {
-ms-overflow-style: none;
scrollbar-width: none;
}
</style>Additionally, update the <html> tag to remove the scrollbar-hide class,
resulting in:
<html lang="en" class="scroll-pt-16">The SEO Configuration is designed to empower users in optimizing their website's visibility on search engines and social media platforms. This documentation outlines the implementation details and usage instructions for effectively managing SEO settings.
The SEO configuration has been centralized using the constants.ts file. This
file manages SEO-related data such as page titles, descriptions, structured
data, and Open Graph tags, providing a more structured and manageable approach
to SEO management.
To customize SEO settings, modify the values in the constants.ts file. Key
configurations include SITE, SEO, and OG, allowing developers to define
site-wide SEO parameters.
// constants.ts
export const SITE = {
title: "surveilr",
// Other SITE properties...
};
export const SEO = {
title: SITE.title,
// Other SEO properties...
};
export const OG = {
title: `${SITE.title}: Compliance Services`,
// Other OG properties...
};When applying metadata within our layouts, such as MainLayout.astro, you can
pass the desired metadata values as props to the Meta component:
---
// In MainLayout.astro file
const { meta } = Astro.props;
interface Props {
meta?: string;
}
---
<Meta meta={meta} />For page-specific SEO overrides, developers can pass individual schema properties within specific page files.
---
import { SITE } from "@/data_files/constants";
---
<MainLayout
title={`Example Page | ${SITE.title}`}
structuredData={{
"@type": "WebPage",
// Other structured data properties...
}}
>
<!-- Page content -->
</MainLayout>With this setup, the Meta component receives the custom meta description and
applies it to the page's metadata. If no custom value is passed, the default
from Meta.astro will be used instead.
For a more robust SEO strategy, you can create additional properties in the
Meta.astro component. For instance, you may want to include specific Open
Graph tags for article publishing dates or tags for Twitter-specific metadata.
Structured data in JSON-LD format can be managed by the Meta.astro component,
improving how search engines understand our page content and potentially
enhancing search results with rich snippets. Modify the structuredData
property with relevant schema.org types and properties:
<MainLayout
structuredData={{
"@context": "https://schema.org",
"@type": "WebSite",
"name": "surveilr",
"url": "https://surveilr.com",
"description": "Discover top-quality compliance tools and services"
}}
>While the template provides a custom SEO solution, you may choose to utilize an Astro integration such as Astro SEO for additional SEO features and optimizations. Integrating such a package might provide more automated metadata management and additional SEO-focused functionality.
robots.txt is dynamically generated using the code found in
src/pages/robots.txt.ts. This configuration follows the example from the Astro
Docs:
import type { APIRoute } from "astro";
const robotsTxt = `
User-agent: *
Allow: /
Sitemap: ${new URL("sitemap-index.xml", import.meta.env.SITE).href}
`.trim();
export const GET: APIRoute = () => {
return new Response(robotsTxt, {
headers: {
"Content-Type": "text/plain; charset=utf-8",
},
});
};The addition of .vscode/settings.json file in the root directory facilitates
image integration directly into content collections within Markdown editors.
This feature enables effortless creation of Markdown links with media files and
seamless copying into the workspace.
- Paste/Drop Images: Activate by pressing Shift while dropping the file.
- Markdown Link: Image is linked using Markdown syntax
(). - File Handling: Images are organized in
src/images/content/<path>.
Pasting getting-started.png into src/content/post-1.md results in:
- Adding
topost-1.md. - Moving the image file to
src/images/content/post-1/getting-started.png.
Note
Remember to press Shift while dropping images.
Maximize our website's efficiency with these built-in Astro integrations:
- Astro Compressor:
Automatically compresses Astro-generated site using gzip or brotli, ensuring
faster load times. Configure the compressor in
astro.config.mjsfile:
export default defineConfig({
// ...other Astro configurations
integrations: [...other Astro integrations, compressor({ gzip: false, brotli: true })],
});- Astro Sitemap:
Automatically generates a sitemap for a website, which is vital for SEO and
helping search engine bots crawl pages effectively. To set up the Astro
Sitemap, be sure to specify our site's base URL and any additional options in
astro.config.mjsfile:
export default defineConfig({
// ...
site: "https://example.com",
integrations: [sitemap()],
});- Bag of Tricks for Astro's View Transitions: is a collection of extensions and support aimed at enhancing Astro's view transitions. Whether you're looking to add flair to our website or streamline user experience, this toolkit offers various techniques to elevate our projects. In the template, it was used to add View Transitions to a Starlight docs.
The great thing about Astro is its rich ecosystem of integrations, allowing you to tailor project functionalities to our exact needs. Feel free to explore Astro integrations page and add additional capabilities as you see fit.
This project is built using a variety of tools and technologies that enhance its performance, maintainability, and developer experience. Below is a list of the key tools and their roles in the project:
Interactive components like navbars, modals, and accordions are built using Preline UI, a comprehensive open-source component library.
Styling across our project leverages the utility-first classes offered by Tailwind CSS. This methodology allows us to create custom layouts and components with speed and efficiency.
To ensure consistent code formatting, particularly for class sorting, we have
integrated the prettier-plugin-tailwindcss
plugin. The
following configuration is set in the .prettierrc file at the root of the
project:
{
"plugins": ["prettier-plugin-tailwindcss"]
}We deploy our project on Vercel, capitalizing on their
robust platform for seamless CI/CD workflows. Using vercel.json, we set
stringent security headers and caching policies, ensuring adherence to security
and performance best practices:
{
"headers": [
{
"source": "/(.*)",
"headers": [
{
"key": "Content-Security-Policy",
"value": "default-src 'self'; [other-directives]"
},
"Additional security headers..."
]
}
]
}For optimal site performance, we post-process our HTML files with
process-html.mjs, a
custom script
that minifies HTML after the build phase to reduce file size and improve load
times.
Here is a snippet from our HTML minification script in process-html.mjs:
/process-html.mjs
// Post-build HTML minification script snippet
// ...
await Promise.all(
files.map(async (file) => {
// File processing and minification logic
})
);We encourage you to refer to the detailed documentation for each tool to fully understand their capabilities and how they contribute to the project: