From ac4b4ec307b7b7ee9372d3d36c854ab263191d7f Mon Sep 17 00:00:00 2001 From: Oscar Levin Date: Mon, 17 Jun 2024 11:47:27 -0700 Subject: [PATCH 1/3] start documentation --- docs/landing_page.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 docs/landing_page.md diff --git a/docs/landing_page.md b/docs/landing_page.md new file mode 100644 index 00000000..384ae6b3 --- /dev/null +++ b/docs/landing_page.md @@ -0,0 +1,15 @@ +# Creating a landing page for your project + +**Note**: The following documentation is aspirational. Not all features are currently implemented. + +Often you will want to host multiple versions and formats of your project on your webpage for the book. The following describes how you can accomplish this. + +## Four Options for Deploying your Project + +When running `pretext deploy`, you can get four different resutls. + +1. Deploy a single target (the default `web` target) at the root of your github pages site. This is the default behavior. +1. Deploy one or more targets with a bare-bones landing page that is automatically generated for you. To get this option, include a `@deploy-dir` attribute for each target you want hosted, with a value that is the relative path to where on the website the target should live. You should not have a `site` folder in your project directory (if you do, rename it something like `_site` so it is ignored). +1. Deploy one or more targets with a static landing page (or multiple pages) that you create yourself and store in the `sites` directory. Each project that should be deployed must have a `@deploy-dir` attribute. You must have a `sites` directory, and it should **not** have a `pelicanconf.py` file present. +1. Deploy one or more targets with a landing page (or multiple pages) that pretext will generate for you using [pelican](https://getpelican.com/). Set up your `sites` directory following the pelican documentation, which means it will include the main configuration file, `pelicanconf.py`. + From d636420a310f4ff2d46a2b27e196de4365feca13 Mon Sep 17 00:00:00 2001 From: Oscar Levin Date: Mon, 17 Jun 2024 12:43:43 -0700 Subject: [PATCH 2/3] fix typo --- docs/landing_page.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/landing_page.md b/docs/landing_page.md index 384ae6b3..7d8db92d 100644 --- a/docs/landing_page.md +++ b/docs/landing_page.md @@ -6,7 +6,7 @@ Often you will want to host multiple versions and formats of your project on you ## Four Options for Deploying your Project -When running `pretext deploy`, you can get four different resutls. +When running `pretext deploy`, you can get four different results. 1. Deploy a single target (the default `web` target) at the root of your github pages site. This is the default behavior. 1. Deploy one or more targets with a bare-bones landing page that is automatically generated for you. To get this option, include a `@deploy-dir` attribute for each target you want hosted, with a value that is the relative path to where on the website the target should live. You should not have a `site` folder in your project directory (if you do, rename it something like `_site` so it is ignored). From 1feab06604fbc12846cbd5b6af1406b94e03c1e5 Mon Sep 17 00:00:00 2001 From: Oscar Levin Date: Thu, 27 Jun 2024 14:50:18 -0600 Subject: [PATCH 3/3] update docs --- docs/landing_page.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/landing_page.md b/docs/landing_page.md index 7d8db92d..ec79fff3 100644 --- a/docs/landing_page.md +++ b/docs/landing_page.md @@ -11,5 +11,17 @@ When running `pretext deploy`, you can get four different results. 1. Deploy a single target (the default `web` target) at the root of your github pages site. This is the default behavior. 1. Deploy one or more targets with a bare-bones landing page that is automatically generated for you. To get this option, include a `@deploy-dir` attribute for each target you want hosted, with a value that is the relative path to where on the website the target should live. You should not have a `site` folder in your project directory (if you do, rename it something like `_site` so it is ignored). 1. Deploy one or more targets with a static landing page (or multiple pages) that you create yourself and store in the `sites` directory. Each project that should be deployed must have a `@deploy-dir` attribute. You must have a `sites` directory, and it should **not** have a `pelicanconf.py` file present. -1. Deploy one or more targets with a landing page (or multiple pages) that pretext will generate for you using [pelican](https://getpelican.com/). Set up your `sites` directory following the pelican documentation, which means it will include the main configuration file, `pelicanconf.py`. +1. Deploy one or more targets with a landing page (or multiple pages) that pretext will generate for you using [pelican](https://getpelican.com/). Your `sites` directory must be set up to use pelican, which means it will include the main configuration file, `pelicanconf.py`. + +The CLI will provide a template pelican site for you, but you are welcome to set up the site following the documentation for pelican. In that case, the CLI will essentially run `pelican content` from the sites directory and copy the `output` directory of sites to the staging directory. + +A faster way to start your landing page is to use the template provided by the CLI. To do this, run: + +``` +pretext init site +``` + +from within your project. + +This will create