feat(config): add host and base_path support for site URLs

Author: Akagi201

.github/workflows/deploy-pages.yml

@@ -31,6 +31,8 @@ jobs:
           config: config.toml
           output: public
           working-directory: examples/blog
+          host: https://longcipher.github.io
+          base-path: /typstify
 
       - name: Deploy to GitHub Pages
         uses: JamesIves/github-pages-deploy-action@v4

.github/workflows/deploy-worker.yml

@@ -26,6 +26,8 @@ jobs:
           config: config.toml
           output: public
           working-directory: examples/blog
+          host: https://typstify-example-blog.workers.dev
+          base-path: ""
 
       - name: Fix permissions
         if: always()

action.yml

@@ -23,6 +23,12 @@ inputs:
     description: 'Include draft posts in build'
     required: false
     default: 'false'
+  host:
+    description: 'Override site host (e.g., https://example.com)'
+    required: false
+  base-path:
+    description: 'Override site base path (e.g., /my-blog)'
+    required: false
   working-directory:
     description: 'Working directory (relative to repository root)'
     required: false

bin/typstify/src/cmd/build.rs

@@ -11,9 +11,22 @@ use super::check::quick_validate;
 /// Run the build command.
 ///
 /// Builds the static site from content files to the output directory.
-pub fn run(config_path: &Path, output: &Path, drafts: bool) -> Result<()> {
+pub fn run(
+    config_path: &Path,
+    output: &Path,
+    drafts: bool,
+    host: Option<&str>,
+    base_path: Option<&str>,
+) -> Result<()> {
     let start = Instant::now();
-    tracing::info!(?config_path, ?output, drafts, "Starting build");
+    tracing::info!(
+        ?config_path,
+        ?output,
+        drafts,
+        ?host,
+        ?base_path,
+        "Starting build"
+    );
 
     // Load configuration
     let mut config = Config::load(config_path).wrap_err("Failed to load configuration")?;
@@ -35,6 +48,18 @@ pub fn run(config_path: &Path, output: &Path, drafts: bool) -> Result<()> {
     // Include drafts if flag is set
     config.build.drafts = drafts;
 
+    // Override host if specified via CLI
+    if let Some(h) = host {
+        tracing::info!(host = h, "Overriding site host from CLI");
+        config.site.host = h.to_string();
+    }
+
+    // Override base_path if specified via CLI
+    if let Some(bp) = base_path {
+        tracing::info!(base_path = bp, "Overriding site base_path from CLI");
+        config.site.base_path = bp.to_string();
+    }
+
     tracing::debug!(?config, "Loaded configuration");
 
     // Create builder with content and output directories

bin/typstify/src/cmd/check.rs

@@ -250,11 +250,11 @@ fn check_directories(result: &mut ValidationResult) {
 
 /// Check configuration values for common issues.
 fn check_config_values(config: &Config, result: &mut ValidationResult) {
-    // Check base_url
-    if config.site.base_url.is_empty() {
-        result.add_warning("site.base_url is empty");
-    } else if !config.site.base_url.starts_with("http") {
-        result.add_warning("site.base_url should start with http:// or https://");
+    // Check host
+    if config.site.host.is_empty() {
+        result.add_warning("site.host is empty");
+    } else if !config.site.host.starts_with("http") {
+        result.add_warning("site.host should start with http:// or https://");
     }
 
     // Check title

bin/typstify/src/lib.rs

@@ -17,7 +17,14 @@
 //! use typstify::cmd;
 //!
 //! // Build a static site
-//! cmd::build::run(Path::new("config.toml"), Path::new("public"), false).unwrap();
+//! cmd::build::run(
+//!     Path::new("config.toml"),
+//!     Path::new("public"),
+//!     false,
+//!     None,
+//!     None,
+//! )
+//! .unwrap();
 //! ```
 
 pub mod cmd;

bin/typstify/src/main.rs

@@ -38,6 +38,12 @@ enum Commands {
         /// Include draft posts
         #[arg(long)]
         drafts: bool,
+        /// Override site host (e.g., https://example.com)
+        #[arg(long)]
+        host: Option<String>,
+        /// Override site base path (e.g., /my-blog)
+        #[arg(long)]
+        base_path: Option<String>,
     },
     /// Start development server with live reload
     Watch {
@@ -72,8 +78,19 @@ async fn main() -> Result<()> {
     typstify::init_tracing(cli.verbose);
 
     match cli.command {
-        Commands::Build { output, drafts } => {
-            typstify::cmd::build::run(&cli.config, &output, drafts)?;
+        Commands::Build {
+            output,
+            drafts,
+            host,
+            base_path,
+        } => {
+            typstify::cmd::build::run(
+                &cli.config,
+                &output,
+                drafts,
+                host.as_deref(),
+                base_path.as_deref(),
+            )?;
         }
         Commands::Watch { port, open } => {
             typstify::cmd::watch::run(&cli.config, port, open).await?;
@@ -104,9 +121,16 @@ mod tests {
         assert_eq!(cli.verbose, 0);
 
         match cli.command {
-            Commands::Build { output, drafts } => {
+            Commands::Build {
+                output,
+                drafts,
+                host,
+                base_path,
+            } => {
                 assert_eq!(output, std::path::PathBuf::from("dist"));
                 assert!(!drafts);
+                assert!(host.is_none());
+                assert!(base_path.is_none());
             }
             _ => panic!("Expected Build command"),
         }
@@ -179,4 +203,27 @@ mod tests {
         let cli = Cli::parse_from(args);
         assert_eq!(cli.config, std::path::PathBuf::from("site.toml"));
     }
+
+    #[test]
+    fn test_cli_build_with_host_and_base_path() {
+        let args = [
+            "typstify",
+            "build",
+            "--host",
+            "https://example.com",
+            "--base-path",
+            "/blog",
+        ];
+        let cli = Cli::parse_from(args);
+
+        match cli.command {
+            Commands::Build {
+                host, base_path, ..
+            } => {
+                assert_eq!(host.as_deref(), Some("https://example.com"));
+                assert_eq!(base_path.as_deref(), Some("/blog"));
+            }
+            _ => panic!("Expected Build command"),
+        }
+    }
 }

crates/typstify-core/src/config.rs

@@ -43,8 +43,14 @@ pub struct SiteConfig {
     /// Site title.
     pub title: String,
 
-    /// Base URL for the site (e.g., "https://example.com").
-    pub base_url: String,
+    /// Host URL for the site (e.g., "https://example.com").
+    /// This is the origin without any path.
+    pub host: String,
+
+    /// Base path for subdirectory deployments (e.g., "/typstify").
+    /// Empty string for root deployments.
+    #[serde(default)]
+    pub base_path: String,
 
     /// Default language code.
     #[serde(default = "default_language")]
@@ -280,25 +286,45 @@ impl Config {
             return Err(CoreError::config("site.title cannot be empty"));
         }
 
-        if self.site.base_url.is_empty() {
-            return Err(CoreError::config("site.base_url cannot be empty"));
+        if self.site.host.is_empty() {
+            return Err(CoreError::config("site.host cannot be empty"));
         }
 
-        // Ensure base_url doesn't have trailing slash
-        if self.site.base_url.ends_with('/') {
-            tracing::warn!("site.base_url should not have a trailing slash");
+        // Ensure host doesn't have trailing slash
+        if self.site.host.ends_with('/') {
+            tracing::warn!("site.host should not have a trailing slash");
+        }
+
+        // Ensure base_path starts with / if not empty
+        if !self.site.base_path.is_empty() && !self.site.base_path.starts_with('/') {
+            tracing::warn!("site.base_path should start with /");
         }
 
         Ok(())
     }
 
+    /// Get the full base URL (host + base_path).
+    #[must_use]
+    pub fn base_url(&self) -> String {
+        let host = self.site.host.trim_end_matches('/');
+        let base_path = self.site.base_path.trim_end_matches('/');
+        format!("{host}{base_path}")
+    }
+
     /// Get the full URL for a path.
     pub fn url_for(&self, path: &str) -> String {
-        let base = self.site.base_url.trim_end_matches('/');
+        let base = self.base_url();
         let path = path.trim_start_matches('/');
         format!("{base}/{path}")
     }
 
+    /// Get the base path for URL generation.
+    /// Returns the configured base_path, ensuring no trailing slash.
+    #[must_use]
+    pub fn base_path(&self) -> &str {
+        self.site.base_path.trim_end_matches('/')
+    }
+
     /// Check if a language code is configured (either as default or in languages map).
     #[must_use]
     pub fn has_language(&self, lang: &str) -> bool {
@@ -355,7 +381,7 @@ mod tests {
         r#"
 [site]
 title = "Test Site"
-base_url = "https://example.com"
+host = "https://example.com"
 default_language = "en"
 
 [languages.zh]
@@ -392,7 +418,7 @@ paginate = 20
         let config = Config::load(&config_path).expect("load config");
 
         assert_eq!(config.site.title, "Test Site");
-        assert_eq!(config.site.base_url, "https://example.com");
+        assert_eq!(config.site.host, "https://example.com");
         assert_eq!(config.site.default_language, "en");
         assert!(config.has_language("en"));
         assert!(config.has_language("zh"));
@@ -416,7 +442,7 @@ paginate = 20
         let minimal_config = r#"
 [site]
 title = "Minimal Site"
-base_url = "https://example.com"
+host = "https://example.com"
 "#;
         std::fs::write(&config_path, minimal_config).expect("write");
 
@@ -430,37 +456,14 @@ base_url = "https://example.com"
         assert_eq!(config.rss.limit, 20);
     }
 
-    #[test]
-    fn test_url_for() {
-        let dir = tempfile::tempdir().expect("create temp dir");
-        let config_path = dir.path().join("config.toml");
-        let config_content = r#"
-[site]
-title = "Test"
-base_url = "https://example.com"
-"#;
-        std::fs::write(&config_path, config_content).expect("write");
-
-        let config = Config::load(&config_path).expect("load config");
-
-        assert_eq!(
-            config.url_for("/posts/hello"),
-            "https://example.com/posts/hello"
-        );
-        assert_eq!(
-            config.url_for("posts/hello"),
-            "https://example.com/posts/hello"
-        );
-    }
-
     #[test]
     fn test_config_validation_empty_title() {
         let dir = tempfile::tempdir().expect("create temp dir");
         let config_path = dir.path().join("config.toml");
         let config_content = r#"
 [site]
 title = ""
-base_url = "https://example.com"
+host = "https://example.com"
 "#;
         std::fs::write(&config_path, config_content).expect("write");
 
@@ -480,4 +483,73 @@ base_url = "https://example.com"
         assert!(result.is_err());
         assert!(result.unwrap_err().to_string().contains("not found"));
     }
+
+    #[test]
+    fn test_base_path_empty() {
+        let dir = tempfile::tempdir().expect("create temp dir");
+        let config_path = dir.path().join("config.toml");
+        let config_content = r#"
+[site]
+title = "Test"
+host = "https://example.com"
+"#;
+        std::fs::write(&config_path, config_content).expect("write");
+        let config = Config::load(&config_path).expect("load");
+        assert_eq!(config.base_path(), "");
+        assert_eq!(config.base_url(), "https://example.com");
+    }
+
+    #[test]
+    fn test_base_path_subdirectory() {
+        let dir = tempfile::tempdir().expect("create temp dir");
+        let config_path = dir.path().join("config.toml");
+        let config_content = r#"
+[site]
+title = "Test"
+host = "https://longcipher.github.io"
+base_path = "/typstify"
+"#;
+        std::fs::write(&config_path, config_content).expect("write");
+        let config = Config::load(&config_path).expect("load");
+        assert_eq!(config.base_path(), "/typstify");
+        assert_eq!(config.base_url(), "https://longcipher.github.io/typstify");
+    }
+
+    #[test]
+    fn test_base_path_with_trailing_slash() {
+        let dir = tempfile::tempdir().expect("create temp dir");
+        let config_path = dir.path().join("config.toml");
+        let config_content = r#"
+[site]
+title = "Test"
+host = "https://longcipher.github.io/"
+base_path = "/typstify/"
+"#;
+        std::fs::write(&config_path, config_content).expect("write");
+        let config = Config::load(&config_path).expect("load");
+        assert_eq!(config.base_path(), "/typstify");
+        assert_eq!(config.base_url(), "https://longcipher.github.io/typstify");
+    }
+
+    #[test]
+    fn test_url_for() {
+        let dir = tempfile::tempdir().expect("create temp dir");
+        let config_path = dir.path().join("config.toml");
+        let config_content = r#"
+[site]
+title = "Test"
+host = "https://example.com"
+base_path = "/blog"
+"#;
+        std::fs::write(&config_path, config_content).expect("write");
+        let config = Config::load(&config_path).expect("load");
+        assert_eq!(
+            config.url_for("/posts/hello"),
+            "https://example.com/blog/posts/hello"
+        );
+        assert_eq!(
+            config.url_for("posts/hello"),
+            "https://example.com/blog/posts/hello"
+        );
+    }
 }