Integrating Markup into a 1C-Bitrix Template
The markup developer delivered static HTML with CSS and JS. Now it needs to become a working Bitrix template, where the header is header.php with a dynamic menu via bitrix:menu, the news block is the bitrix:news.list component, and the contact form is bitrix:form.result.new. This is not a mechanical copy-paste of HTML: integration requires understanding how Bitrix manages data, caching, and rendering.
Integrating Markup into a 1C-Bitrix Template
What Integration Means
Integration is the process of converting static HTML/CSS/JS into a dynamic Bitrix system. Input: markup files (HTML, CSS, JS, images). Output: a fully functional site template in /local/templates/, where static blocks have been replaced by components and data comes from the database.
This is a distinct technical task that often takes as long as the markup itself — especially if the markup developer did not account for Bitrix-specific constraints.
Integration Stages
Splitting HTML into the template. Static HTML is divided into header.php (from <html> to the end of the header), footer.php (footer through </html>), and component zones. CSS and JS are moved to the template folder; paths are corrected using SITE_TEMPLATE_PATH.
Resource inclusion. In header.php, resources are connected via $APPLICATION->SetAdditionalCSS() or directly in <head>. JS is better placed before </body> in footer.php. If the markup developer used npm packages, a build step is needed.
Replacing static blocks with components. Navigation — bitrix:menu with an overridden template. The homepage slider — typically bitrix:main.include with an editable area file, or a custom component based on an info block. News list — bitrix:news.list. Form — bitrix:form.result.new.
Migrating component styles. Standard components ship with their own CSS that may conflict with the markup. Solutions: include the component's style.css and override the relevant rules, or create a component template from scratch without including the default styles.
Common Integration Problems
Image and file paths — static markup uses relative paths (../images/logo.png); in Bitrix, SITE_TEMPLATE_PATH or absolute paths must be used. Otherwise images will not display on pages not at the root.
jQuery conflicts — markup often bundles its own jQuery while Bitrix includes its own. Solution: remove the markup's jQuery, use BX.ready() instead of $(document).ready(), or explicitly call jQuery.noConflict().
Cyrillic in IDs and class names — occasionally found in Bitrix-targeted markup. Bitrix adds its own bx- prefixed classes — these must not conflict with class names in the markup.
Admin toolbar — when a site administrator is logged in, Bitrix adds a bar at the top of the page (~45px). If the markup uses a position: fixed header calculated from the top, the bitrix-admin class on <html> must be accounted for.
Case Study: Landing Page Integration
A marketing agency developed landing page markup for a client: 8 sections, a custom slider, a multi-step form, animations using Intersection Observer. The client wanted to edit text through the Bitrix admin panel.
We split the landing page: static sections with text — via bitrix:main.include with editable areas (so editors can update text without touching code), slider — info block + custom bitrix:news.list template, form — bitrix:form.result.new with an overridden template that preserves the multi-step JS logic. Animations were left untouched — they live in the template's script.js and work independently. Integration took 3 business days.
Timeline
| Markup type | Timeline |
|---|---|
| Simple landing page (1–3 pages, basic blocks) | 1–3 days |
| Corporate site (5–20 pages, standard components) | 1–2 weeks |
| Online store (catalog, cart, checkout) | 2–5 weeks |