1. Install
- Go to Appearance > Themes > Add New > Upload Theme, choose
mosaicly-1.0.0.zip, click Install Now, then Activate.
- The Mosaicly Engine plugin is bundled inside the theme. It installs and activates itself when you activate the theme, and every theme update brings the matching engine update. You do not need to install anything else.
- You land on Mosaicly > Dashboard, which shows your stats and a setup checklist.
Requirements: WordPress 6.5+, PHP 7.4+, the GD or Imagick image library and pretty permalinks (Set up my site turns them on for you).
2. Set up my site (one click)
Open Mosaicly > Set up my site, pick a site preset (Ideas for everything, Design and interiors, or Food and recipes) and click the button. It creates:
- Pages: Home, Ideas (the app), Log in, Sign up, Community guidelines and Privacy. Pins, boards and profiles get clean links such as
/ideas/pin/12/, /ideas/board/4/ and /ideas/u/alex/.
- The main menu and the footer menu. The footer year updates itself.
- Optional sample content: six members, seven boards and thirty pins with original images, saves, follows, comments and reactions, so the feed looks alive while you test.
Running it again is safe. It never duplicates pages, menus or sample content.
3. Pins
- Create (the + button): upload an image, or paste a web address and click Fetch. The engine reads the page's preview image, title and description for you. Add a title, description, destination link and tags, then choose a board and section, or make a new board on the spot.
- Images are re-saved on your server with thumbnails, and the main colour is stored, so pins can be found by colour.
- Hashtags in a description become tags automatically. Turn on Approve new pins in Settings to hold every new pin for review.
- The close-up page shows the full image, the source link, the creator with a Follow button, Save, reactions, comments and a More like this feed.
4. Boards, sections and collaborators
- Boards can be public or secret. Secret boards are only visible to the owner and collaborators. You can limit free secret boards in Settings; members get unlimited secret boards.
- Sections split a board into groups (for example "Kitchen" and "Bathroom" inside "Home ideas").
- Collaborators: the owner invites members by username. Collaborators can add pins to the board.
- Anyone can Save (repin) a pin to one of their boards from the grid or the close-up, and follow members or single boards.
5. Feed, explore and search
- Home shows new pins from the people and boards you follow. New members see popular pins until they follow someone.
- Explore has Popular, Newest and trending tags. Every grid is a masonry layout with lazy-loaded images and infinite scroll.
- Search by keyword, by tag (
#tag) and by colour swatch.
- On phones the layout switches to two columns with a bottom tab bar.
- Profiles have Created, Saved and Boards tabs, follower counts and a Follow button.
6. Comments, reactions and notifications
- Members comment on pins, reply to comments and react with one of five reactions.
- Notifications (the bell) cover new followers, saves of your pins, comments, replies, reactions, collaborator invites, moderation outcomes and purchases. The count refreshes on its own (the interval is in Settings).
7. Reporting and moderation
- Members can report a pin, comment, board or person with a reason.
- Mosaicly > Reports lists open and closed reports. Remove takes the content down and closes the report; Close dismisses it. The creator is notified.
- Pins: filter by All, Pending, Live, Promoted, Hidden or Removed; approve, hide, remove (with a note) or promote for 7 days for free.
- Boards: hide or restore. Members: suspend or restore, or grant a 30-day membership.
- Blocked words (Settings) stop pins and comments that contain them. Rate limits stop flooding.
8. Promoted pins and creator membership
- Promoted pins: a creator opens a pin and clicks Promote, picks a plan (default 3, 7 or 30 days) and pays by card through Stripe Checkout. Promoted pins carry a clear Promoted label and are mixed into feeds every N pins (Settings: Promoted every).
- Creator membership (optional, default name "Creator Plus"): monthly or yearly plans. Members get a badge, unlimited secret boards and a discount on promotions. Rename it, change prices or leave plans empty to switch it off.
- All orders and revenue appear under Mosaicly > Orders & revenue. Refunds are made in your Stripe dashboard and are marked here automatically when the webhook is set up.
Plan lines use the format key|Label|days|price, one per line.
9. Stripe and the webhook
- In Stripe, open Developers > API keys and copy your secret key (
sk_test_… while testing, sk_live_… when live) into Mosaicly > Settings > Stripe secret key. You can also define MZ_STRIPE_SECRET in wp-config.php.
- Add a webhook at Developers > Webhooks pointing to
https://your-site.com/wp-json/mz/v1/stripe with the event checkout.session.completed, and paste its signing secret (whsec_…) into Settings.
- No webhook yet? Purchases still activate: when the buyer returns from Checkout the engine confirms the session with Stripe directly. Each payment is applied only once.
Test with card 4242 4242 4242 4242, any future date and any CVC.
10. Settings
| Setting | What it does |
|---|
| Community name, tagline, brand colour | Name in the top bar and emails, the home hero text and the accent colour. |
| Preset | Wording used across the site. |
| Approve new pins / open sign-up / pins from web pages | Moderation and access switches. |
| Max image size, pins per page, promoted every | Upload limit (MB), grid page size and how often promoted pins appear. |
| Rate limits, blocked words | Pins and comments per hour; words that block posting. |
| Currency, promotion plans, membership name, plans, discount, free secret boards | Everything you sell. |
| Stripe secret key, webhook secret | Payments (see section 9). |
Mosaicly > System shows versions, tables and Stripe status.
11. Going live
- In Set up my site, click Remove sample content. Real members, their pins and orders are never touched.
- Switch Stripe to your live key and live webhook secret.
- Edit the Community guidelines and Privacy pages for your site.
- Set the site title and tagline in Settings > General, and add a logo in the Site Editor if you like.
12. FAQ
Pins from a web address say "could not be reached".
Some sites block automated requests or have no preview image. Upload the image instead.
Links show "Page not found".
Go to Settings > Permalinks and click Save, or run Set up my site again.
A payment went through but the pin is not promoted.
Check the webhook secret, or open the order under Orders & revenue. The return fallback confirms paid sessions when the buyer comes back.
Can I translate it?
Yes. All text uses the mosaicly text domain.
Can I change the look?
Yes. It is a block theme: use Appearance > Editor for templates, colours and fonts. Change the brand colour in Settings.