Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: coatless-quarto/adsense
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: 1.0.0
Choose a base ref
...
head repository: coatless-quarto/adsense
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: main
Choose a head ref

Commits on Dec 6, 2023

  1. Add release note

    coatless committed Dec 6, 2023
    Copy the full SHA
    065ea0f View commit details
  2. Disable adding sites

    coatless committed Dec 6, 2023
    Copy the full SHA
    2eb5ecb View commit details
  3. Copy the full SHA
    80bba2a View commit details
  4. Copy the full SHA
    daf3802 View commit details
  5. Copy the full SHA
    2cd9b8f View commit details
  6. Copy the full SHA
    776a821 View commit details
  7. Copy the full SHA
    9a305fb View commit details
  8. Bump extension version and add release note

    coatless committed Dec 6, 2023
    Copy the full SHA
    0700b73 View commit details
  9. Change check order enable-ads: false

    coatless committed Dec 6, 2023
    Copy the full SHA
    9819b7e View commit details

Commits on Dec 7, 2023

  1. Improve type detection for true/false

    and error messages.
    coatless committed Dec 7, 2023
    Copy the full SHA
    c6b6575 View commit details
  2. Re-position website to be under docs/

    coatless committed Dec 7, 2023
    Copy the full SHA
    290d41c View commit details
  3. Remove debug check

    coatless committed Dec 7, 2023
    Copy the full SHA
    0fe5960 View commit details
  4. Add release notes page onto the website

    coatless committed Dec 7, 2023
    Copy the full SHA
    9c9326d View commit details
  5. Emphasize the enable-ads part

    coatless committed Dec 7, 2023
    Copy the full SHA
    5263fe7 View commit details
  6. Add a disclaimer

    coatless committed Dec 7, 2023
    Copy the full SHA
    b7b6cc9 View commit details
  7. Reorganize the pages

    coatless committed Dec 7, 2023
    Copy the full SHA
    59abc01 View commit details
  8. Add FAQ page and list issue submission

    coatless committed Dec 7, 2023
    Copy the full SHA
    b0be639 View commit details
  9. Re-organize the website and update the README file

    coatless committed Dec 7, 2023
    Copy the full SHA
    4aa3051 View commit details
  10. Stage a release

    coatless committed Dec 7, 2023
    Copy the full SHA
    5093c42 View commit details
  11. Update qgads-release-notes.qmd

    coatless authored Dec 7, 2023

    Verified

    This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
    Copy the full SHA
    dae6791 View commit details
  12. Tweak title

    coatless committed Dec 7, 2023
    Copy the full SHA
    360400e View commit details

Commits on Dec 13, 2023

  1. Add documentation regarding the ads.txt file (#2)

    * Add documentation regarding the `ads.txt` file
    
    * Minor tweak
    coatless authored Dec 13, 2023

    Verified

    This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
    Copy the full SHA
    40c90e3 View commit details
1 change: 1 addition & 0 deletions .github/workflows/publish-website.yml
Original file line number Diff line number Diff line change
@@ -28,3 +28,4 @@ jobs:
uses: quarto-dev/quarto-actions/publish@v2
with:
target: gh-pages
path: docs
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -2,5 +2,5 @@
*.pdf
*_files/
/.luarc.json

*_site/
/.quarto/
79 changes: 74 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# adsense: A Quarto Extension for Adding Google Adsense to Quarto HTML Projects
# quarto-adsense: A Quarto Extension for Google Adsense

The `adsense` extension allows you to incorporate [Google Adsense](https://adsense.google.com/start/) ad's on various [Quarto](https://quarto.org/) formats, including [HTML](https://quarto.org/docs/output-formats/html-basics.html), [Websites](https://quarto.org/docs/websites/), and [Books](https://quarto.org/docs/books).
The `adsense` extension allows you to incorporate [Google Adsense (GADS)](https://adsense.google.com/start/) ad's on various [Quarto](https://quarto.org/) formats, including [HTML](https://quarto.org/docs/output-formats/html-basics.html), [Websites](https://quarto.org/docs/websites/), and [Books](https://quarto.org/docs/books).

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/coatless-quarto/adsense)

@@ -22,7 +22,16 @@ This command will download and install the extension under the `_extensions` sub

## Usage

Open either the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html#project-metadata) or [`_metadata.yml`](https://quarto.org/docs/projects/quarto-projects.html#directory-metadata) Project file and add the following:
There are two modes available for the extension:

1. A global configuration that allows a consistent option to be set for multiple pages with an option to opt a page out.
2. A localized single page configuration.

**Note:** Ads may take up to an hour to appear on the page/project.

### Multi-page Projects: Websites and Books

If you have a website or book, you can use either the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html#project-metadata) or [`_metadata.yml`](https://quarto.org/docs/projects/quarto-projects.html#directory-metadata) files to avoid needing to consistently set the value. Add into the configuration file:

```yml
adsense:
@@ -32,14 +41,70 @@ filters:
- adsense
```
where `ca-pub-XXXXXXXXXXXXXXXX` in `publisher-id` is your Google Adsense [Publisher ID](https://support.google.com/adsense/answer/105516?hl=en).
where `XXXXXXXXXXXXXXXX` in `publisher-id` is your Google Adsense [Publisher ID](https://support.google.com/adsense/answer/105516?hl=en).

**Note:** Ads may take up to an hour to appear on the page/project.
If you wish to disable ads on a specific page, then add to the Quarto document's YAML header area:

```yml
adsense:
enable-ads: false
```

For more information, please see Quarto's documentation on [Shared Metadata](https://quarto.org/docs/projects/quarto-projects.html#shared-metadata).

### Single Page Projects: HTML Document

If you only have one HTML document, we recommend setting up the extension by placing the required fields into the document's header section, e.g.

```yml
---
title: "Demo Setup"
author: "FirstName LastName"
adsense:
publisher-id: ca-pub-XXXXXXXXXXXXXXXX
filters:
- adsense
---
```

### Google Adsense Setup: Adding `ads.txt`

To ensure smooth integration with Google Adsense, it's essential to create a [standalone file named `ads.txt`](https://support.google.com/adsense/answer/12171612) within your project directory that identifies the domain as being authorized to serve ads. Follow these steps to include the `ads.txt` file:

1. **Create `ads.txt` File:**
In the root of your project, create a new file named `ads.txt`.

2. **Add Google Publisher ID:**
Open `ads.txt` and insert the following line, replacing `XXXXXXXXXXXXXXXX` with your actual [Google Publisher ID](https://support.google.com/adsense/answer/105516?hl=en):

```
google.com, pub-XXXXXXXXXXXXXXXX, DIRECT, f08c47fec0942fa0
```
This line informs Google's web crawler about your association with the provided Publisher ID. For an example, please see the [`docs/ads.txt`](https://github.com/coatless-quarto/adsense/blob/main/README.md).
3. **Save and Include in Version Control:**
Save the changes to `ads.txt` and ensure that the file is included in your version control system if you're using one.
4. **Register `ads.txt` in _quarto.yml:**
Open the `_quarto.yml` configuration and add the `resources` line under the project key.
```yaml
project:
type: website # default, book, revealjs
resources:
- ads.txt
```

This ensures the additional file resources are copied to the output directory.

This step is crucial for validating your ownership of the website and enabling a smooth interaction between your Quarto-generated content and Google Adsense. Remember to replace `XXXXXXXXXXXXXXXX` with your specific Google Publisher ID.

## References

- Google Adsense
- [Google Adsense: Find Publisher ID](https://support.google.com/adsense/answer/105516?hl=en)
- [Google Adsense: Ads.txt guide](https://support.google.com/adsense/answer/12171612)
- [Google Adsense: Get and copy the AdSense code](https://support.google.com/adsense/answer/9274019?hl=en)
- [Google Adsense: Where to place the AdSense code in your HTML](https://support.google.com/adsense/answer/9274516?sjid=14850419192472362507-NC)
- Quarto
@@ -49,3 +114,7 @@ where `ca-pub-XXXXXXXXXXXXXXXX` in `publisher-id` is your Google Adsense [Publis
- [Pandoc: Lua Filters](https://pandoc.org/lua-filters.html)
- [Pandoc: Lua type reference](https://pandoc.org/lua-filters.html#lua-type-reference)
- [Lua: Manual](https://www.lua.org/manual/5.4/)

## Disclaimer

This Quarto extension is open source software and is **not affiliated with** Google. The extension is at best a community effort to simplify the integration of Google's Adsense product inside of Quarto websites.
2 changes: 1 addition & 1 deletion _extensions/adsense/_extension.yml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
title: Adsense
author: James Balamuta
version: 1.0.0
version: 2.0.0
quarto-required: ">=1.3.0"
contributes:
filters:
102 changes: 79 additions & 23 deletions _extensions/adsense/adsense.lua
Original file line number Diff line number Diff line change
@@ -1,11 +1,40 @@
----
--- Setup variables for default initialization

-- Check to see if we've already defined the adsense Unit
-- Note: This should only trigger _once_
local isAdsenseUnitMissing = true

local function isEmptyString(s)
-- Check to see if we should show ads on the given page
local enableAds = true

----
--- Process initialization

-- Check if variable is present and not just the empty string
local function isVariableEmpty(s)
return s == nil or s == ''
end

local function stringHasContents(s)
return not isEmptyString(s)
local function isVariablePopulated(s)
return not isVariableEmpty(s)
end

-- Check if a value is true or false, including string representations
local function isBoolean(value)
if type(value) == "boolean" then
return true
elseif type(value) == "string" then
local lowercaseValue = value:lower()
return lowercaseValue == "true" or lowercaseValue == "false"
else
return false
end
end

-- Coerce a "true" or "false" string to `true`/`false`.
local function stringToBoolean(str)
return str == "true" and true or false
end

-- Ad unit HTML
@@ -22,32 +51,59 @@ end
-- Retrieve publisher and setup ad unit
function Meta(m)

-- Detect HTML format (excluding epub which won't handle fa)
if not quarto.doc.is_format("html:js") then
quarto.log.error("The `adsense` extensions works only on HTML powered Quarto projects.")
end

-- Check for configuration
local adsense_meta = m.adsense
if isEmptyString(adsense_meta) then
quarto.log.error("The Quarto project is missing the `adsense` key in either the document header, `_quarto.yml`, or `_metadata.yml`.")
if isVariableEmpty(adsense_meta) then
quarto.log.error(
"The Quarto project is missing the `adsense` key in either" ..
"\n - the document header,\n - `_quarto.yml`, or\n - `_metadata.yml`."
)
end

-- Detect HTML format (excluding epub which won't handle fa)
if quarto.doc.is_format("html:js") then

-- Retrieve publisherID from meta
local publisher_id = pandoc.utils.stringify(adsense_meta['publisher-id'])
if stringHasContents(publisher_id) then
if isAdsenseUnitMissing then
-- Avoid re-running insertion
isAdsenseUnitMissing = false
-- Customize the ad unit script tag
local adsense_customized_adunit_html = adsense_html(publisher_id)
-- Inject the customized unit into the HTML document's header section
-- using Quarto's API.
quarto.doc.include_text("in-header", adsense_customized_adunit_html)
end
else
quarto.log.error("The `publisher-id` is not set. Please set the `publisher-id` by either the value in the current document, the projects `_quarto.yml`, or `_metadata.yml` for the directory.")
-- Retrieve enable-ads from meta
if isVariablePopulated(adsense_meta['enable-ads']) then
enableAds = pandoc.utils.stringify(adsense_meta['enable-ads'])

if not isBoolean(enableAds) then
quarto.log.error("The `enable-ads` must be either `true` or `false`, not `" .. enableAds .. "`." ..
"\nPlease fix by correcting the value supplied to `enable-ads` in the current document.")
end

-- Apply conversion from string to boolean
enableAds = stringToBoolean(enableAds)

-- If ads should be disabled; exit here to avoid running into a publisher-id unset error.
if enableAds == false then
return m
end
end

-- Retrieve publisherID from meta
local publisher_id = nil
if isVariablePopulated(adsense_meta['publisher-id']) then
publisher_id = pandoc.utils.stringify(adsense_meta['publisher-id'])
else
quarto.log.error("The `adsense` extensions works only on HTML powered Quarto projects.")
quarto.log.error(
"The `publisher-id` is not set. Please set the `publisher-id` by either:" ..
"\n - the value in the current document," ..
"\n - the projects `_quarto.yml`, or" ..
"\n - `_metadata.yml` for the directory.\n")
end

if enableAds and isAdsenseUnitMissing then
-- Avoid re-running insertion
isAdsenseUnitMissing = false
-- Customize the ad unit script tag
local adsense_customized_adunit_html = adsense_html(publisher_id)
-- Inject the customized unit into the HTML document's header section
-- using Quarto's API.
quarto.doc.include_text("in-header", adsense_customized_adunit_html)
end

return m
end
19 changes: 0 additions & 19 deletions _quarto.yml

This file was deleted.

1 change: 1 addition & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
/.quarto/
1 change: 1 addition & 0 deletions docs/_extensions
40 changes: 40 additions & 0 deletions docs/_quarto.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
project:
type: website

website:
title: "adsense"
reader-mode: true
repo-url: https://github.com/coatless-quarto/adsense/
repo-actions: [edit, issue]
sidebar:
style: "floating"
search: true
tools:
- icon: github
href: https://github.com/coatless-quarto/adsense/
contents:
- text: "Home"
file: index.qmd
- text: "Installation"
file: qgads-installation.qmd
- section: "Demos"
contents:
- qgads-ad-global-configuration.qmd
- qgads-ad-localized-page.qmd
- qgads-ad-free-page.qmd
- section: "Support"
contents:
- text: "FAQ"
href: qgads-faq.qmd
- text: "Submit an issue"
href: https://github.com/coatless-quarto/adsense/issues/new/choose
- section: "Extra"
contents:
- qgads-release-notes.qmd

# Register Adsense plugin to appear on all pages
adsense:
publisher-id: ca-pub-4979996562647159

filters:
- adsense
1 change: 1 addition & 0 deletions docs/ads.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
google.com, pub-XXXXXXXXXXXXXXXX, DIRECT, f08c47fec0942fa0
11 changes: 11 additions & 0 deletions docs/index.qmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
title: "Home"
---

The `adsense` extension allows you to incorporate [Google Adsense](https://adsense.google.com/start/) ad's on various [Quarto](https://quarto.org/) formats, including [HTML](https://quarto.org/docs/output-formats/html-basics.html), [Websites](https://quarto.org/docs/websites/), and [Books](https://quarto.org/docs/books). This extension is required as [Quarto does **not** natively support Google Adsense](https://github.com/quarto-dev/quarto-cli/discussions/2898#discussioncomment-3905621), but [does have support for Google Analytics](https://quarto.org/docs/websites/website-tools.html#google-analytics).

Ready to get started? Check out the [installation steps](qgads-installation.qmd) and the preferred [setup approach using a global configuration](qgads-ad-global-configuration.qmd).

:::{.callout-important}
This Quarto extension is open source software and is **not affiliated with** Google. The extension is at best a community effort to simplify the integration of Google's Adsense product inside of Quarto websites.
:::
22 changes: 22 additions & 0 deletions docs/qgads-ad-free-page.qmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
---
title: "Enabling an Ad-Free Page with Global Configuration"
adsense:
enable-ads: false
---

## Overview

This example demonstrates how to disable ads on specific pages by utilizing a YAML configuration setting. By following these steps, you can easily prevent the insertion of Google Adsense units on individual pages, ensuring an ad-free experience for your users on pages that you do not wish to monetize.

## Configuration

To disable ads on a per-page basis, insert the following code snippet into the YAML header of the desired page:

```yaml
adsense:
enable-ads: false
```
## Result
Upon setting `enable-ads` to `false`, the Google Adsense unit will not be included in the specified page. Consequently, ads will be effectively disabled, providing a cleaner and ad-free presentation for users accessing that particular page.
39 changes: 39 additions & 0 deletions docs/qgads-ad-global-configuration.qmd
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
---
title: "Global Adsense Configuration for Multi-page Projects"
---

## Overview

This example demonstrates how to globally enable ads across all webpages by specifying options in either the [`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html#project-metadata) or [`_metadata.yml`](https://quarto.org/docs/projects/quarto-projects.html#directory-metadata) files. This allows you to avoid the need for repetitive configurations by centralizing the setup.

## Global Configuration

To globally set Adsense parameters for your project, insert the following snippet into the chosen metadata file ([`_quarto.yml`](https://quarto.org/docs/projects/quarto-projects.html#project-metadata) or [`_metadata.yml`](https://quarto.org/docs/projects/quarto-projects.html#directory-metadata)):

```yaml
adsense:
publisher-id: ca-pub-XXXXXXXXXXXXXXXX
filters:
- adsense
```
This configuration ensures that the specified Google Adsense publisher ID is applied consistently across all pages within your project.
To find your Google Adsense publisher ID, please see Google's [Find your Publisher ID](https://support.google.com/adsense/answer/105516?hl=en) documentation.
## Page-specific Configuration
If you need to disable ads on a specific page, you can easily do so by adding the following YAML code to the header area of the document:
```yaml
adsense:
enable-ads: false
```
This local configuration takes precedence over the global settings, allowing for fine-grained control on a per-page basis.
For more detailed insights into shared metadata and global configurations, refer to Quarto's documentation on [Shared Metadata](https://quarto.org/docs/projects/quarto-projects.html#shared-metadata).
## Result
Ads should now be served across all pages or a directory of pages on your Quarto website.
Loading